Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
CommandDescription
pushUpload a file as an artifact
pullDownload an artifact
lsList artifacts with filters
inspectShow detailed artifact metadata
linkCreate a temporary download URL
rmDelete artifacts
session lsList sessions with artifact counts and seal status
session newGenerate a new session ID (local operation, no server call)
session sealSeal a session (prevent new uploads)
whoamiShow tenant info and usage
auth loginAuthenticate with an API key
configRead/write CLI configuration

​
Global behavior

BehaviorDetail
Output formatHuman-readable by default. --json for JSON. Auto-JSON when stdout is piped. --human to force human output in pipes.
Exit codes0 success, 1 client error, 2 server error, 3 network error
Config file~/.config/artifacta/config.toml
Auth priorityARTIFACTA_API_KEY env var > config file
Destructive actionsartifacta 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

VariableDefaultDescription
ARTIFACTA_API_KEY—API key (overrides config file)
ARTIFACTA_API_URLhttps://api.artifacta.ioAPI base URL
ARTIFACTA_OUTPUThumanOutput format: human or json
ARTIFACTA_TTL30dDefault 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