Commands
| Command | Description |
|---|
push | Upload a file as an artifact |
pull | Download an artifact |
ls | List artifacts with filters |
inspect | Show detailed artifact metadata |
rm | Delete artifacts |
link | Create a temporary download URL |
extend-ttl | Extend artifact expiration |
session new | Generate a session ID locally |
session seal | Seal a session (prevent new uploads) |
whoami | Show tenant info and usage |
config | Read/write CLI configuration |
auth login | Authenticate with an API key |
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 |
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.
Environment variables
| Variable | Default | Description |
|---|
ARTIFACTA_API_KEY | — | API key (overrides config file) |
ARTIFACTA_API_URL | https://api.artifacta.dev | 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) |
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'
