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.

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.
• 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.