Skip to main content
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

curl -fsSL https://hostartifacts.dev/install.sh | sh
The public installer requires Node.js 24+, downloads the Node-based CLI, and installs it to ~/.local/bin/artifacts. It then shows an interactive picker so you choose which coding agents receive the agent-artifacts skill (via Vercel’s skills CLI). 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

​
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

artifacts login
artifacts whoami
Browser login stores bearer tokens in the OS credential store: secret-tool/libsecret on Linux, Keychain on macOS, and Credential Manager on Windows. The local ~/.config/agent-artifacts/credentials.json file contains only non-secret metadata such as service URLs. On Linux, install secret-tool and unlock your keyring before running artifacts login.

​
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:
CodeMeaning
0Success
2Invalid request
3Not found
4Forbidden or authentication failure
5Conflict
69Retryable 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.