Scripting & agents

This page is for coding agents and scripts that run artor. If you use the CLI yourself, the CLI reference is all you need.

JSON output

Commands marked [--json] in the CLI reference print machine-readable output on stdout. Everything else (progress, notices, the target line below) goes to stderr, so stdout stays parseable.

• Single items include a target object naming the organization and account the command acted in. Lists (including artor account list) are a bare array with no target.
• artor open --json prints the URL without opening a browser; artor open --signed-in --json prints { url, authUrl, expiresAt } and opens no browser.
• artor status --json sets orgsStale: true when the saved organization list couldn’t be refreshed, so a “not a member” answer may be out of date.

artor account list --json

A bare array: one { "kind": "account", ... } row per signed-in login, then one { "kind": "pending", "apiUrl": ... } row per login made by an older CLI that isn’t identified yet. Tokens are never included.

• An account row’s status is ok, invalid (run artor login again), suspended, deletion_pending, unreachable, or error.
• A pending row has a reason: unreachable, suspended, deletion_pending, unsaved, or error (with httpStatus). Running artor account list again usually identifies it.

Review-anchor notes (agentNotes)

artor init and artor publish keep a Review anchors (Artor) section in the project’s AGENTS.md (or CLAUDE.md), asking the agent to tag elements with data-testid so comment pins stay on them. See Making a prototype easy to review.

With --json, both commands add an agentNotes field:

"agentNotes": {
  "files": ["AGENTS.md"],
  "status": "added",
  "hint": "..."
}

status is added, updated, current, disabled or failed. hint appears when the notes were added, updated or failed. The section sits between artor review anchors comment markers; anything you write inside them is replaced. Skip it for one run with --no-agent-notes, or for the folder with "agentNotes": false in .artor/project.json. Turning it off never removes an existing section.

Review widget update (webSdk)

artor publish --json adds a webSdk field reporting what happened to the review widget:

"webSdk": {
  "status": "updated",
  "declared": "latest",
  "from": "0.13.0",
  "to": "0.14.0"
}

status is updated, current, pinned, skipped or failed. declared is the version listed in package.json before this publish, or null when the widget isn’t a dependency or the file couldn’t be read. skipped means publish deliberately didn’t try (--no-sdk-update, no widget dependency, a prebuilt publish, a project with no lockfile of its own inside a workspace, an unreadable Yarn version, or a widget that isn’t installed); a registry or install problem is failed. Under --json no update line is printed.

A retried publish (replayed)

If the reply to a publish is lost, the CLI asks again with the same key, and Artor answers with the version that already went live instead of publishing a second one (artor-cli 0.35.0 or later). The result then adds replayed: true. Treat it like any successful publish: the version in the result is the one this run created. Its URL is that version’s own numbered link when latest or the named link has moved on to a newer version since. If a run fails after a lost attempt, the error says the version may already be live: check the prototype’s versions in the dashboard before an agent publishes again, because a new run is a new publish. The error codes a script can see are listed in If the connection drops during a publish.

artor registry list --json

A bare array, one row per connected package scope ([] when there are none). Each row adds proxyAvailable: true when Artor can serve that scope, false when the organization’s registry proxy is off or its plan doesn’t include it (so artor registry login writes nothing), and null from an older Artor server that doesn’t report it. false doesn’t tell you whether artor registry add would succeed. When the proxy isn’t available, the note saying so goes to stderr, also when the list is empty. Needs artor-cli 0.34.2 or later.

Non-interactive runs

With no terminal, or with --json, the CLI never prompts.

• Say where to act. If the account or organization can’t be worked out on its own, pass --org <ref>, plus --account <email> when more than one of your accounts belongs to it. See Organization context.
• Confirm explicitly. Destructive commands need --yes (-y) and an exact name or ID, not a partial match. artor rm --permanent needs --confirm "<exact name>"; --yes alone isn’t enough.
• Pass every choice as a flag. init files the prototype in the Organization Space’s Draft folder unless you pass --space / --folder; a folder name that doesn’t exist stops setup rather than being created. share set needs a flag to know what to change. An unattended share add without --comments uses the organization’s default; with --comments, it prints the link and then exits 1 if the server didn’t apply that choice or can’t confirm it. A --comments value other than off, members, anyone, name or name-email exits 1 before anything is sent. share list --json gives each link’s choice as comments (off, members, anyone, name or name_email). These five --comments values need CLI 0.33.0 or newer; an older CLI rejects members and anyone, so run artor update first.
• Secrets from a pipe. Use --password-stdin for link passwords and env set KEY --stdin for values, so they never land in shell history. --password=<value> is refused. If the organization requires link passwords, an unattended share add without a password flag is refused.
• env and mock stay in the linked folder’s organization. In an unlinked folder with more than one possible organization they refuse. For them, --org is a deprecated alias for --scope org, not an organization selector.
• unlink with no flags removes only the project link when there’s no terminal.

The target line

Before acting, most commands print one line to stderr naming the organization, account, and (when known) Space, folder or prototype, for example -> acme · you@x.com · Client work / Checkout redesign.

Organization checks

Commands confirm the organization against your live membership list just before changing anything. If the list changed (you left, the organization was renamed, or --org now resolves differently), the command refuses and changes nothing; run artor account list to refresh, then retry. In a folder linked to one organization, an --org naming another is refused, with no --force exemption: run artor unlink --link-only first, or run from another folder.

Flags

• --flag value and --flag=value both work.
• A flag that needs a value but gets none (the next word is another flag, or it’s the last word) stops the command with exit code 1 before anything is fetched or written.
• For a note, label or description that starts with --, use the = form: --message=--hotfix.
• An empty value is accepted for text flags, but not for --dir, --space or --folder.

Environment variables

Project-local installs, npx and CI never update themselves; they print a notice instead.