# Scripting & agents

> How the CLI behaves when a coding agent or script runs it — JSON output, non-interactive runs, and environment variables.
> URL: https://artor.app/docs/cli-scripting

This page is for coding agents and scripts that run `artor`. If you use the CLI yourself, the
[CLI reference](https://artor.app/docs/cli) is all you need.

## JSON output

Commands marked `[--json]` in the [CLI reference](https://artor.app/docs/cli) 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](https://artor.app/docs/comments#making-a-prototype-easy-to-review).

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

```json
"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](https://artor.app/docs/cli#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

| Variable | Effect |
| --- | --- |
| `ARTOR_NO_AUTOUPDATE=1` | Skip automatic CLI and skill updates for this run. |
| `ARTOR_SKILL_AUTO_UPDATE=0` | Turn off only the skill's automatic update. |
| `ARTOR_GITHUB_TOKEN` | Token for adding a skill from a private GitHub repository (`artor skill add`). |
| `ARTOR_REGISTRY_TOKEN` | Upstream token for `artor registry add`. |
| `NO_COLOR` / `FORCE_COLOR` | Disable or force terminal colors. `NO_COLOR` wins. |

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