# CLI reference

> Find commands for publishing, reviewing, sharing, and setting up your team.
> URL: https://artor.app/docs/cli

Use the `artor` CLI to publish prototypes, read feedback, and manage your team's shared setup.
Run commands from your prototype's folder. If you haven't installed it yet, follow
[Installing the CLI](https://artor.app/docs/install-cli).

**Note:** 
  Commands marked with the lock icon require an owner/admin role, or a Space admin where specified. Skills and templates use the
  organization's [manager setting](https://artor.app/docs/skills#permission-gate), which defaults to admins.
  Project changes may also require a [publisher seat](https://artor.app/docs/seats) and Space access.

If you belong to more than one organization, check [Organization context](https://artor.app/docs/cli#organization-context)
before running commands in a new folder.

## Help, references, and confirmations

- **Help:** `artor <command> --help`, `-h`, or `artor help <command>` shows usage without
  running the command. Help works offline and before sign-in.
- **Names:** most commands accept an exact name, ID, or unique part of a name. If several
  items match, Artor asks you to be more specific. `link` needs an exact project ID or slug.
- **Confirmations:** destructive commands ask first. `--yes` or `-y` skips that question;
  unattended runs must include it when required. Use exact names or IDs when skipping
  confirmation for deletion, sharing, or access changes.
- **Overwriting files:** `pull --force` needs exact project and organization references.
  It overwrites local files, so save anything you need first. `skill pin --yes` also needs
  an exact skill reference.
- **Flags:** `--flag value` and `--flag=value` both work. Always provide the target value
  for organization, scope, version, and mode selectors.
- **Agent output:** use `--json` where listed below for output an agent or script can read.
- **Color:** `NO_COLOR` disables terminal colors. `FORCE_COLOR` enables them in redirected
  output; `NO_COLOR` takes priority.

For a public link, copy its ID from `artor share list`, or use a unique prefix of at least
four characters. For a comment thread, use its full ID, short ID, or a quoted row number
such as `"#3"`. Use the same `--version`, `--open`, and guest filters you used to list it.

## Version & update checks

| Command | Description |
| --- | --- |
| `--version` / `-V` | Show the installed CLI version. |
| `update` | Update the CLI and your installed Artor skill. For a project-local or `npx` install, follow the command it prints. |
| `install` | Choose which Artor agent integration to install. |
| `install-claude-plugin` | Install or update the Claude Code plugin. |
| `install-skills` / `install-skill` | Install the Artor skill in other supported coding tools. |
| `update-skill [claude-plugin\|skills]` | Update just the installed skill. |
| `update --off` / `update --on` | Disable or enable automatic CLI updates. |

Global and packaged installations can update automatically after an interactive command.
Project-local installations, `npx`, and CI show an update notice instead. Set
`ARTOR_NO_AUTOUPDATE=1` to disable automatic CLI updates for one run.

If an upgrade is required to continue, an eligible installation updates and retries the
command once. Otherwise, run `artor update` when prompted.

The CLI also reminds you when an Artor skill update is available. For optional automatic
Claude Code plugin updates, see [Keeping the skill up to date](https://artor.app/docs/skills#keeping-the-skill-up-to-date).

## Auth & project

| Command | Description |
| --- | --- |
| `login` | Open your browser to sign in and authorize this machine. |
| `whoami [--json]` | Show your signed-in account and active organization. |
| `status [--json]` | Show this folder's linked prototype and organization; report setup problems. |
| `logout` | Remove the locally stored token. Revoke it in the dashboard to disable it everywhere. |
| `init [--name <n>] [--org <ref>] [--space <ref>] [--folder <name\|id>] [--template <ref>] [--here] [--no-install] [--no-git] [--json]` | Create and link a prototype in this folder. Artor asks where it belongs; use the flags to choose directly. `--template` uses a team starter, `--here` uses this folder, and `--no-git` skips Git setup. See [Getting started](https://artor.app/docs/getting-started). |
| `link [<id\|slug>] [--org <ref>] [--force]` | Link this folder to an existing prototype using its exact ID or slug. Use `--force` to replace an existing link. |
| `unlink [--all] [--skills] [--npmrc] [--link-only]` | Local-only detach — removes the link and other local setup, never your code or the server project. See [Unlinking a folder](https://artor.app/docs/cli#unlinking-a-folder). |
| `org list [--json]` | List the organizations you belong to; a star marks your saved default. |
| `org use [<ref>]` | Save a default organization for commands run outside a linked folder. Omit the reference for a picker. |
| `org members` | List the organization's members and roles; use their email addresses when adding people to Spaces. |
| `project list [--json]` / `project search <query> [--json]` | Browse or search prototypes in the active organization. |

Without a terminal or destination flags, `init` uses the Organization Space's Draft folder.
`--folder` selects an existing exact name or ID, or creates a folder if that name is new.
An organization or Space that can't be found stops setup; Artor doesn't silently choose another.

## Publish & view

| Command | Description |
| --- | --- |
| `publish` / `push [--alias <name> \| -v <name>] [-m <text>] [--label <text>] [--dir <path>] [--static] [--no-build] [--no-install] [--no-smoke] [--no-sdk-update] [--mocks=local\|server] [--yes] [--json]` | Build and publish. `latest` moves to the published version; `--alias` (or `-v`) also updates a named link. Prefer `--alias` over the deprecated publish flag `--version`. See [Publishing & frameworks](https://artor.app/docs/publishing) for flags and version modes. |
| `pull [--ref <r>] [--dir <path>] [--project <ref>] [--org <ref>] [--force]` | Download a version's source and stay linked to its prototype. `--project` selects another prototype; `--force` overwrites local files and relinks the folder, requiring exact references. Environment and credential files are excluded. Private-package setup uses your own login; see [Private registry](https://artor.app/docs/registry). |
| `dump [--all-versions] [--out <dir>]` | Export all accessible prototype source to `./artor-dump` (or `--out`). Add `--all-versions` for history. Existing files are preserved; failed downloads are reported. Each run uses a dump credit: Starter gets 2 per 30 days; paid plans get 1 per 24 hours. If unavailable, the command says when to retry. Single-project `pull` has no dump allowance. |
| `remix <project> [name] [--name <n>] [--ref <r>] [--dir <path>] [--org <ref>]` | Create an independent prototype from another version. Choose a name; the destination must be empty. Run `artor publish` from the new folder when ready. See [Remix](https://artor.app/docs/remix). |
| `rename [<ref>] "New Name" [--org <ref>]` | Rename a project's display name (owner/admin only). |
| `rm [<ref>] [--org <ref>] [--yes]` Admin access required | Move a project to the trash. Recoverable for 30 days. |
| `restore <ref> [--org <ref>]` Admin access required | Restore a trashed project. |
| `trash [--org <ref>] [--json]` | List trashed projects in the active organization and how long each has left. |
| `open [--version <n>] [--alias <name>] [--json]` | Open a version in the browser. With `--json`, print the URL without opening a browser. |
| `logs [ref] [--json]` | Read recent output from a running prototype or its captured startup error. Defaults to `latest`. See [Reading logs](https://artor.app/docs/cli#reading-a-crashed-versions-logs). |
| `comments [--version <ref>] [--open] [--guests-only \| --no-guests] [--json]` | Read feedback for the linked prototype, defaulting to `latest`. `--open` shows unresolved threads. Choose one guest filter to include only or exclude guest feedback. Guest names are unverified. See [Comments](https://artor.app/docs/comments#reading-comments-from-the-cli). |
| `comments resolve <thread> [listing flags] [--json]` / `comments reopen <thread> [listing flags] [--json]` | Mark a thread handled or reopen it. `<thread>` may be its full id, short id, or a quoted row such as `"#3"`. Reuse the same listing flags you used to find it. See [Resolving from the CLI](https://artor.app/docs/comments#resolving-from-the-cli). |
| `comments ignore <thread> [listing flags] [--json]` / `comments unignore <thread> [listing flags] [--json]` | Exclude a thread from AI work, or include it again. See [Excluding a thread from AI](https://artor.app/docs/comments#excluding-a-thread-from-ai). |

### Changelog

Every version can carry a short note explaining what changed. Add it when publishing:

```bash
artor publish -m "Fixed navigation on mobile"
artor publish --message "Updated the signup screen from review feedback"
```

The note appears beside the version in the dashboard. Owners and admins can edit it there
later; changing the note does not change the prototype.

Notes support text and Markdown links, up to **2,000 characters**. Images and embeds are not
included. An empty note is ignored; an oversized note must be shortened before publishing.

The [Artor Claude Code skill](https://artor.app/docs/skills#the-artor-claude-code-skill) can draft the note from
your changes. Review it before publishing. A message you provide yourself takes priority.

### Reading a crashed version's logs

```bash
artor logs latest
artor logs v3 --json
```

Read a prototype's error output to help your coding agent fix it. Use an alias or version
number; without one, the command uses `latest`. You can also open the version's **Details →
Logs** in the dashboard.

A running version shows its recent output. A version that failed to start shows the captured
startup error. If no output was captured, Artor reports “No logs captured.” Startup capture
is limited to **512 KB per version** and does not cover a crash that happens after startup.

Artor hides exact matches of saved environment values from logs. It may not recognize a
value your prototype changed before printing, so check logs before sharing them. See
[Runtime errors](https://artor.app/docs/runtime-errors) for next steps.

## Public sharing

Create a public link so someone without an Artor account can open a prototype. Choose
whether they can comment when creating the link. See
[Public sharing](https://artor.app/docs/sharing) for links, durations, and guest commenting.

| Command | Description |
| --- | --- |
| `share add [--mode latest\|pinned] [--deployment <id>] [--days <n>] [--warn] [--comments off\|anonymous\|name\|name-email] [--hide-widget] [--password \| --password-stdin]` | Create a link. `latest` follows new publishes; `pinned` selects `--deployment`. Duration defaults to 7 days, within the organization's limit (maximum 90). `--warn` requests an expiry reminder. `--comments` chooses guest commenting; otherwise the terminal prompts with the organization default, and scripts use that default. `--hide-widget` creates the link with the in-page review widget hidden from signed-in organization members; it takes no value. `--password` asks for a [link password](https://artor.app/docs/cli#link-passwords); `--password-stdin` reads it from a pipe. |
| `share list [--json]` / `share ls [--json]` | List links and copy live URLs. A live link shows `password` when it asks for one, or `needs a password` when the organization requires one and this link has none. Expired, turned-off, or older links may require a fresh share before you can copy a URL. |
| `share set <share> [--comments off\|anonymous\|name\|name-email] [--password \| --password-stdin \| --remove-password]` | Change a live link's guest-commenting setting, its password, or both in one call. Put the password flags after the link id. The terminal prompts for a commenting mode if no flag is given; scripts must pass a flag. Expired or turned-off links require a fresh share. |
| `share extend <share> [--days <n>]` | Extend a live link from now, within the organization's duration limit. Restarts an opted-in expiry reminder. Expired or turned-off links cannot be extended. |
| `share off <share>` | Turn off a link permanently. A full ID needs no prompt; a partial ID requires interactive confirmation. |

`<share>` is a link id from `artor share list`, or a unique prefix of one (at least four
characters, resolved against the linked prototype's own links). A full id works from anywhere.

A live link's guest-commenting mode and its password are changeable from either surface:
`share set` here, or **Edit** on the link's row in the dashboard's Public sharing panel.
Whether signed-in members see the review widget can be set when you create the link
(the dashboard's "Show the review widget" switch, or `--hide-widget` here), and changed
later in that same **Edit** dialog. **Allow new comments** and repointing a link to
another version stay dashboard-only, in that same **Edit** dialog.

`share set` needs a current CLI. Run `artor update` if the command isn't recognised.

### Link passwords

A public link can ask visitors for a password before it opens. Add one when creating the
link, or set, change, and remove it later:

```bash
artor share add --password                # prompts, hidden, typed twice
printf %s "$LINK_PASSWORD" | artor share add --password-stdin
artor share set <share> --password        # change a live link's password
artor share set <share> --remove-password # remove it
```

A password is **never a flag value**: `--password=secret` is refused, so the password can't
land in your shell history or process list. `--password` prompts for it twice and checks the
rules (8 to 128 characters) on the first entry. `--password-stdin` reads it from a pipe for
scripts, dropping one trailing newline.

`--remove-password` is refused while your organization requires a password on public links.
When that requirement is on and you run `share add` without a password flag, an interactive
terminal says so and asks for one, then creates the link. An unattended run stops with an
error naming the two flags.

Link passwords require CLI **0.26.0** or newer. Against an older Artor deployment the
command exits with an error saying the password was not set, and reports any commenting
change that did apply. See [Public sharing](https://artor.app/docs/sharing#password-protection).

## Spaces

A **Space** decides which organization members can open and work on a group of prototypes. See [Spaces](https://artor.app/docs/spaces).

| Command | Description |
| --- | --- |
| `space list [--json]` | List the Spaces you can see. |
| `space create <name>` | Create a shared Space (Team plan or higher). You become its first admin. |
| `space rename <space> "<new>"` Admin access required | Rename a shared Space (Space admin or organization admin). |
| `space read <space> on\|off` Admin access required | Let every organization member open and comment on this Space's prototypes, without being able to change anything. Space admin or organization admin. |
| `space rm <space> [--yes]` Admin access required | Delete an **empty** shared Space. |
| `space rm <space> --move-to <folder> [--yes]` Admin access required | Move the Space's prototypes (trashed included) into a folder elsewhere, then delete it. |
| `space members <space>` | List a shared Space's members. |
| `space members <space> add <email-or-id> [--role admin\|member]` Admin access required | Add a member or change their role (Space admin or org admin). |
| `space members <space> rm <email-or-id>` Admin access required | Remove a member (Space admin or org admin). |

`<space>` accepts an id, name, or unique part of the name. For `space read` and
`space members add|rm`, a partial match on a terminal is confirmed with the full Space name
before the change. Pre-approved and non-interactive runs require an exact reference. Members
are referenced by email or user id; run `artor org members` for the roster. See
[Spaces](https://artor.app/docs/spaces#from-the-cli).

## Folders

Group prototypes into colored folders **within a Space**. Folders organize work; Spaces
determine access. See [Organizing with folders](https://artor.app/docs/folders). Folder commands act on the **linked folder's organization** —
run them inside a folder linked to organization A and you manage organization A's folders.

| Command | Description |
| --- | --- |
| `folder list [--space <name\|id>] [--json]` | List folders and how many prototypes each holds. |
| `folder create [<name>] [--color <c>] [--space <name\|id>]` | Create a folder (prompts if omitted). A duplicate name or the reserved name **Draft** is rejected. |
| `folder rename <name\|id> "<new>"` | Rename a folder (Draft can't be renamed). |
| `folder color <name\|id> [<color\|none>]` | Set or clear a folder's color. |
| `folder move [<project>] [<folder>] [--space <name\|id>]` | Move a prototype into a folder, optionally in another Space. |
| `folder rm <name\|id> [--with-content] [--yes]` | Delete a folder; prototypes move to Draft, or with `--with-content` Admin access required are trashed too. |
| `folder clear <name\|id> [--yes]` Admin access required | Trash every prototype in a folder, keeping the folder. |

A folder is referenced by id or name, a prototype by id, slug, or name. Both accept a unique
partial match, and `--space <name|id>` scopes `list` / `create` / `move` to another Space.
`folder rm` and `folder clear` require an exact folder reference when run with `--yes` or
without a terminal. See [Organizing with folders](https://artor.app/docs/folders#from-the-cli).

## Env vars

Set configuration for the **organization, a project, or one version**. A linked folder
defaults to project scope. Values marked `--local` can be downloaded; server-only values
cannot. See [Environment variables](https://artor.app/docs/env) for how to choose and use them.

Organization `set` / `rm` require an owner or admin. Project/version changes require a
[publisher seat](https://artor.app/docs/seats) and permission to edit that Space. Members can list names for
prototypes they can access. Pulling project values requires a publisher with source access;
any member can pull organization-wide local values.

| Command | Description |
| --- | --- |
| `env set KEY=VALUE [--local] [--scope org\|project\|version] [--version <ref>]` | Set a value. Project is the default scope in a linked folder. `--local` also allows `env pull` to write it to your machine. |
| `env set KEY --stdin [--local] [scope flags]` | Read the value from a pipe so it does not appear in shell history, for example `printf %s "$SECRET" \| artor env set API_TOKEN --stdin`. |
| `env list [--scope org\|project\|version] [--version <ref>] [--json]` | List names and whether values can be downloaded; values are never shown. |
| `env rm KEY [--scope org\|project\|version] [--version <ref>]` | Remove a variable at the selected scope. |
| `env pull` | Download the linked project's local configuration to `./.env.local`. From an unlinked folder, pull the organization values. Scope flags are not accepted. |

Use `--scope org` for organization values and `--version <ref>` for one version. Prefer
`--scope org` over the deprecated bare `--org`. See [Environment variables](https://artor.app/docs/env#commands).

## Mock datasets

Add sample data for the **organization, a project, or a version**. Published versions keep
their data when organization/project defaults change; explicit version edits change the
selected version. See [Mock datasets](https://artor.app/docs/mock).

Organization writes require an owner or admin. Project/version writes require a
[publisher seat](https://artor.app/docs/seats) and permission to edit the prototype's Space. Members can read
and compare datasets for prototypes they can access.

| Command | Description |
| --- | --- |
| `mock set <name> <file.json> [--scope org\|project\|version] [--version <ref>]` | Upload or replace the mock at the selected scope (project by default). |
| `mock list [--scope org\|project\|version] [--version <ref>] [--json]` | List mock names, sizes, and timestamps — never the bodies. |
| `mock rm <name> [--scope org\|project\|version] [--version <ref>]` | Remove the mock at the selected scope. |
| `mock revisions <name> [--scope org] [--json]` | Show a name's edit history. Project (default) or organization scope; `--version` isn't supported. |
| `mock pin <name> <sha> --version <ref>` | Repoint a published version's mock to an existing revision — no republish. |
| `mock pull` | Download project data to `./mocks/*.json`. Matching local files that differ are overwritten. |
| `mock status [--json]` | Compare local and saved data without changing files. |
| `mock promote <name> [--ref <r>]` Admin access required | Make a version's bundled dataset an organization default. Owner/admin with a publisher seat required. |

Use `--scope org` for shared organization data; the bare `--org` selector is deprecated.
`pull`, `status`, and `promote` use the linked project and take no scope flag. `promote`
selects its source version with `--ref`. See [Who can do what](https://artor.app/docs/mock#who-can-do-what).

## Org skills

Share instructions with your team's AI tools. The commands marked with a lock use the default admin-only
setting; an admin can allow all members to manage skills and templates. See
[Org skills](https://artor.app/docs/skills#permission-gate).

| Command | Description |
| --- | --- |
| `skill add <gh-url> [--name X] [--ref <r>] [--credential <t>] [--enforced]` Admin access required | Add shared instructions from GitHub. `--enforced` makes them mandatory. Private sources require `--credential` or `ARTOR_GITHUB_TOKEN`; the saved token is not shared with teammates. |
| `skill list [--json]` | List organization skills. |
| `skill enforce <name> [--off]` Admin access required | Toggle a skill as organization-mandated. |
| `skill pin <name> [--yes]` Admin access required | Update a skill to its latest version. |
| `skill rm <name> [--yes]` Admin access required | Remove a skill from the whole organization. Confirms first; `--yes` is required without a terminal. |
| `skill sync [--force]` | Download shared skills. Optional local edits are kept unless `--force` is used; mandatory skills always overwrite local edits. |

## Starter templates

| Command | Description |
| --- | --- |
| `template push --name X [--slug y] [--desc z]` Admin access required | Store the current directory as an organization template. |
| `template list` | List organization templates. |

Use a template: `artor init --template <slug>`.

## Usage

| Command | Description |
| --- | --- |
| `usage [--org <ref>] [--json]` Admin access required | Show the organization's plan and its storage, publisher seats, and public link views against the plan's limits. Owner/admin only. |

Without `--org`, this uses the linked folder's organization or your saved default. Storage
measurements are periodic; check the reading's age. The same figures appear in **Settings →
Usage**. See [Usage](https://artor.app/docs/usage).

## Private registry

Map private packages to your organization. See [Private registry](https://artor.app/docs/registry).

| Command | Description |
| --- | --- |
| `registry add <@scope> --type azure\|npmjs [--uplink <url>] [--token <t>] [--name <label>] [--expires <date>]` Admin access required | Map a package scope to a private source. `--name` sets a display label; `--expires <YYYY-MM-DD>` records when the upstream token lapses. The token can also come from `$ARTOR_REGISTRY_TOKEN`. |
| `registry list [--json]` | List configured scopes. |
| `registry login` | Configure your machine to install scoped packages through Artor. |
| `registry rm <@scope>` Admin access required | Remove a mapping. |

## Unlinking a folder

`artor unlink` removes the **local setup** that `init` / `link` wrote. It never deletes
your code, and it never touches the server project (use `artor rm` for that).

| Flag | Effect |
| --- | --- |
| _(none, on a terminal)_ | Interactive checklist (below). |
| `--link-only` | Remove only the project link. |
| `--skills` | Remove only the synced organization skills (`.claude/skills/org/`). |
| `--npmrc` | Strip only the managed `.npmrc` registry block. |
| `--all` | Remove all three in one shot. |

Flags combine — `--skills --npmrc` strips skills and the managed `.npmrc` block while keeping
the project link. With no flags on a terminal, a checklist lets you choose (the project link is
pre-checked; skills and `.npmrc` appear only if present). With no flags and no terminal, it
removes just the project link.

## Organization context

When you belong to more than one organization, commands choose the target in this order:

1. `--org <ref>` on the command line.
2. The organization stamped into the folder's link by `init` / `link`.
3. Your saved default (`artor org use`).
4. The organization you were in when you logged in.

`status` and `whoami` report the **active organization**, the one commands will use, together with your role.
The organization used when you logged in is shown only when it differs.

Commands that act on the linked folder use that folder's organization. Commands that target something
by reference, including `remix`, `pull --project`, `restore`, `rm <ref>`, `rename <ref>`,
`trash`, and `usage`, also accept `--org <ref>`. Without it they follow the same order above,
including the linked folder before the saved default.

If the active organization is stale or you are no longer a member, run `artor org list`, then use
`artor org use <ref>`, pass `--org <ref>`, or re-point the folder with
`artor link --org <ref> <id|slug> --force`.

## Your token

Your login token is stored securely on your computer. Treat it like a password.
`artor logout` signs out locally; revoke the token under **Settings → CLI tokens** to stop it
working everywhere.