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.

This page covers setup and behavior. For the full command list, see the CLI reference.

Install

Public installer

curl -fsSL https://hostartifacts.dev/install.sh | sh

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):

ARTIFACTS_SKILL_AGENTS="cursor claude-code codex" curl -fsSL https://hostartifacts.dev/install.sh | sh

Install only the CLI:

ARTIFACTS_SKIP_SKILLS=1 curl -fsSL https://hostartifacts.dev/install.sh | sh

Skip browser login during install:

ARTIFACTS_SKIP_LOGIN=1 curl -fsSL https://hostartifacts.dev/install.sh | sh

Point it at your services

For local development:

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:

bun run cli:build:prod
bun run cli:install:prod

For public distribution, build release assets:

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:

flags  ->  environment variables  ->  saved credentials  ->  build-time defaults

Authenticate

Browser login

artifacts login
artifacts whoami

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:

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:

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

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

CLI reference

Every command, flag, and environment variable.