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 |
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. |
--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
# 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_TELEMETRY | — | Set to 1 to enable Sentry error reporting (opt-in) |
Agent integration pattern: An orchestrator sets ARTIFACTA_SESSION_ID once in the environment. Every sub-agent inherits it automatically — zero flag passing required.
# Orchestrator sets the session once
export ARTIFACTA_SESSION_ID=$(artifacta session new)
# 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
