CLI Overview - Artifacta

Commands

Discoverable help: artifacta <command> --help shows flags, exit codes, and a worked Examples block on every command. The root artifacta --help also lists every ARTIFACTA_* environment variable, the four exit codes, and a Common workflow guide.

Command	Description
`push`	Upload a file as an artifact
`pull`	Download an artifact
`ls`	List artifacts with filters
`inspect`	Show detailed artifact metadata
`link`	Create a temporary download URL
`rm`	Delete artifacts
`session ls`	List sessions with artifact counts and seal status
`session new`	Generate a new session ID (local operation, no server call)
`session seal`	Seal a session (prevent new uploads)
`whoami`	Show tenant info and usage
`publish`	Upload a file and publish it as a shareable public page
`unpublish`	Take down an artifact’s public page
`auth login`	Authenticate with an API key
`config`	Read/write CLI configuration

Use push --transcript and ls --transcript to store and filter a session’s conversation; see the session transcript guide for precedence and automation.

Artifact Pages commands

`publish`

Uploads a local file as an artifact and immediately publishes it as a shareable page. Visibility defaults to unlisted (accessible via URL, not indexed). The page URL is printed to stdout.

Flag	Default	Description
`--title TEXT`	—	Page title shown in the viewer header.
`--public`	—	Make the page discoverable (mutually exclusive with `--unlisted`).
`--unlisted`	default	Make the page unlisted / URL-only (default when neither flag is set).
`--password TEXT`	—	Password-protect the page. Pro plan required.
`--session TEXT`	env `ARTIFACTA_SESSION_ID`	Attach to a session (same fallback as `push`).
`--agent TEXT`	env `ARTIFACTA_AGENT_ID`	Agent ID — shown in the page’s provenance receipt.
`--meta KEY=VALUE`	—	Metadata key=value (repeatable).
`--model TEXT`	env `ARTIFACTA_MODEL`	Shorthand for `--meta model=<id>`; mutually exclusive with it. Shown in the page’s provenance receipt as a declared producer claim.
`--ttl TEXT`	env `ARTIFACTA_TTL`	Override default TTL.
`--json`	—	Output full response as JSON.
`--human`	—	Force human-readable output even when stdout is piped.

# Publish a file (unlisted by default)
artifacta publish report.pdf

# Publish with a title and make it publicly discoverable
artifacta publish report.pdf --title "Q2 Report" --public

# Publish with password protection (Pro plan)
artifacta publish data.json --password hunter2

# Populate the page's provenance receipt
artifacta publish report.pdf --agent earnings-bot --model claude-fable-5

# Capture the page URL in a script
PAGE_URL=$(artifacta publish report.pdf --json | jq -r '.public_url')

`unpublish`

Takes down an artifact’s public page. The underlying artifact is not deleted. Accepts an artifact ID (art_...) or a page slug (pg_...). The page_id is printed to stdout on success.

Flag	Default	Description
`--json`	—	Output full response as JSON.
`--human`	—	Force human-readable output even when stdout is piped.

artifacta unpublish art_abc123def456
artifacta unpublish pg_slug123
artifacta unpublish art_abc123def456 --json

Global behavior

Behavior	Detail
Output format	Human-readable by default. `--json` for JSON. Auto-JSON when stdout is piped. `--human` to force human output in pipes.
Exit codes	`0` success, `1` client error, `2` server error, `3` network error
Config file	`~/.config/artifacta/config.toml`
Auth priority	`ARTIFACTA_API_KEY` env var > config file
Destructive actions	`artifacta rm` prompts for confirmation; pass `--yes` (or `--force`) to skip the prompt in scripts, or `--dry-run` to preview what would be deleted without committing. `artifacta session seal` is irreversible — sealed sessions cannot accept new artifacts.

Auto-JSON for agents: When stdout is not a TTY (piped or redirected), the CLI automatically outputs JSON. Human-readable output goes to stderr, data to stdout. This means artifacta ls | jq just works.

Destructive actions

The CLI carries verbatim warnings on every destructive command. Read them via --help once before a script run — the wording below is the exact text the CLI prints, and is part of the user-facing contract.

artifacta rm --help — Warning: --session deletes every artifact in that session. Use --dry-run to preview.

artifacta session seal --help — Warning: Sealing is irreversible. Sealed sessions cannot accept new artifacts.

Environment variables

Variable	Default	Description
`ARTIFACTA_API_KEY`	—	API key (overrides config file)
`ARTIFACTA_API_URL`	`https://api.artifacta.io`	API base URL
`ARTIFACTA_OUTPUT`	`human`	Output format: `human` or `json`
`ARTIFACTA_TTL`	`30d`	Default TTL for uploads
`ARTIFACTA_SESSION_ID`	—	Default session_id for `push` (inherited by sub-processes)
`ARTIFACTA_AGENT_ID`	—	Default agent_id for `push` (inherited by sub-processes)
`ARTIFACTA_MODEL`	—	Default `metadata.model` for `push`/`publish` (inherited by sub-processes)
`ARTIFACTA_TELEMETRY`	—	Set to `1` to enable Sentry error reporting (opt-in)

Agent integration pattern: An orchestrator sets ARTIFACTA_SESSION_ID (and optionally ARTIFACTA_MODEL) once in the environment. Every sub-agent inherits them automatically — zero flag passing required. Explicit --model or --meta model= always beats the environment value.

# Orchestrator sets the session once
export ARTIFACTA_SESSION_ID=$(artifacta session new)
export ARTIFACTA_MODEL=claude-fable-5   # declared model for every push

# Every agent inherits it
python agent_a.py   # push calls tagged with session automatically
python agent_b.py   # same session, zero config

Shell scripting patterns

# Upload all CSVs from a directory, capture artifact IDs
for f in ./output/*.csv; do
  artifacta push "$f" --session batch_20260313 | jq -r '.artifact_id'
done > artifact_ids.txt

# Download all artifacts from a session
artifacta ls --session batch_20260313 | \
  jq -r '.artifacts[].artifact_id' | \
  xargs -I{} artifacta pull {} -o ./downloads/

# Generate share links for all artifacts in a session
artifacta ls --session batch_20260313 | \
  jq -r '.artifacts[].artifact_id' | \
  xargs -I{} artifacta link {} --json | jq -r '.url'

# Network-resilient push — auto-idempotency dedupes (same content +
# filename + session + agent), so retries never create duplicate artifacts.
for i in 1 2 3; do
  artifacta push report.pdf --session batch_20260313 && break
  sleep 2
done

​Commands

​Artifact Pages commands

​publish

​unpublish

​Global behavior

​Destructive actions

​Environment variables

​Shell scripting patterns

Commands

Artifact Pages commands

`publish`

`unpublish`

Global behavior

Destructive actions

Environment variables

Shell scripting patterns