> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The agent-friendly command line for local scripts, CI jobs, and coding agents.

The `artifacts` CLI is the recommended interface for local agents, CI jobs, and scripts. It's a deterministic wrapper over the REST API with machine-readable discovery and predictable output.

<Info>
  This page covers setup and behavior. For the full command list, see the [CLI reference](/reference/cli).
</Info>

## Install

<CodeGroup>
  ```bash Public installer theme={"theme":"github-dark"}
  curl -fsSL https://hostartifacts.dev/install.sh | sh
  ```

  ```bash From the monorepo theme={"theme":"github-dark"}
  bun install
  bun run cli:build
  bun run cli:install
  ```

  ```bash Without installing theme={"theme":"github-dark"}
  node apps/cli/dist/cli.js <command>
  ```
</CodeGroup>

The public installer requires Node.js 24+. It shows an interactive picker so you choose which coding agents receive the `agent-artifacts` skill (via Vercel's `skills` CLI), then downloads the Node-based CLI, installs it to `~/.local/bin/artifacts`, immediately starts `artifacts login`, and installs the skill for the selected agents. Agents already installed on your machine are preselected; toggle entries by number, or press Enter to accept. Supported choices include Cursor, Claude Code, Codex, OpenCode, Copilot, Gemini CLI, and Windsurf.

Skip the picker and target specific agents (use `'*'` for all):

```bash theme={"theme":"github-dark"}
ARTIFACTS_SKILL_AGENTS="cursor claude-code codex" curl -fsSL https://hostartifacts.dev/install.sh | sh
```

Install only the CLI:

```bash theme={"theme":"github-dark"}
ARTIFACTS_SKIP_SKILLS=1 curl -fsSL https://hostartifacts.dev/install.sh | sh
```

Skip browser login during install:

```bash theme={"theme":"github-dark"}
ARTIFACTS_SKIP_LOGIN=1 curl -fsSL https://hostartifacts.dev/install.sh | sh
```

## Point it at your services

For local development:

```bash theme={"theme":"github-dark"}
export AGENT_ARTIFACTS_BASE_URL="http://127.0.0.1:3001"
export AGENT_ARTIFACTS_WEB_URL="http://localhost:3000"
```

For production, build a bundled Node CLI with default URLs baked in from `.env`:

```bash theme={"theme":"github-dark"}
bun run cli:build:prod
bun run cli:install:prod
```

For public distribution, build release assets:

```bash theme={"theme":"github-dark"}
bun run cli:build:release:env-file
```

Upload the files from `apps/cli/dist/release/v<version>/` to the matching GitHub Release tag. The public web app on Railway exposes `https://hostartifacts.dev/install.sh` as the memorable installer URL, redirecting to the latest release installer.

URLs resolve in this order:

```text theme={"theme":"github-dark"}
flags  ->  environment variables  ->  saved credentials  ->  build-time defaults
```

## Authenticate

<CodeGroup>
  ```bash Browser login theme={"theme":"github-dark"}
  artifacts login
  artifacts whoami
  ```

  ```bash Bearer token theme={"theme":"github-dark"}
  export AGENT_ARTIFACTS_TOKEN="aa_live_..."
  artifacts whoami --format json
  ```

  ```bash Non-interactive theme={"theme":"github-dark"}
  export AGENT_ARTIFACTS_NO_INPUT=1
  artifacts artifact list --format json
  ```
</CodeGroup>

Browser login saves a bearer token to `~/.config/agent-artifacts/credentials.json` (created with mode `0600`) and keeps you signed in across runs — no OS keyring or D-Bus session required, so it works the same on laptops, headless servers, containers, CI, and AI agents. Check the current state at any time without a network call:

```bash theme={"theme":"github-dark"}
artifacts status
```

`status` always exits `0` and reports `authenticated`, the resolved `baseUrl`, and the credentials file path. Token precedence is `--token` flag → `AGENT_ARTIFACTS_TOKEN` env → saved login file.

## Discovery for agents

Agents should rely on schema discovery rather than parsing `--help`:

```bash theme={"theme":"github-dark"}
artifacts schema
```

The schema includes command names and examples, the HTTP method and path, the JSON body schema, whether a command mutates state, and the global flags and output contract.

## Output contract

The CLI is built for automation:

* JSON by default when stdout isn't a TTY; text in interactive terminals.
* Data on stdout, errors on stderr.
* A stable envelope: `{ "ok": true, "data": ... }` or `{ "ok": false, "error": ... }`.
* `--ndjson` streams list results as one JSON object per line.
* `next_actions` suggest useful follow-up commands.

Exit codes are stable, so scripts can branch on them:

| Code | Meaning                             |
| ---- | ----------------------------------- |
| `0`  | Success                             |
| `2`  | Invalid request                     |
| `3`  | Not found                           |
| `4`  | Forbidden or authentication failure |
| `5`  | Conflict                            |
| `69` | Retryable network failure           |

## Commands you'll reach for

```bash theme={"theme":"github-dark"}
artifacts push --owner alice --project-slug default --file ./report.md
artifacts artifact list --limit 20
artifacts artifact get --artifact-id ARTIFACT_ID
artifacts artifact update --artifact-id ARTIFACT_ID --json '{"content":"# v2"}'
artifacts artifact diff --artifact-id ARTIFACT_ID --from 1 --to 2
artifacts share create --artifact-id ARTIFACT_ID --role viewer
artifacts keys create --name ci --scopes artifacts:read,artifacts:create
```

<Card title="CLI reference" icon="terminal" href="/reference/cli" horizontal>
  Every command, flag, and environment variable.
</Card>