> ## 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.

# CLI Overview

> Global behavior, environment variables, and output conventions for the Artifacta CLI.

## Commands

<Tip>
  **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.
</Tip>

| 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](/guides/transcripts) 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. |

```bash theme={null}
# 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. |

```bash theme={null}
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. |

<Tip>
  **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.
</Tip>

## 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.

<Warning>
  **`artifacta rm --help`** — Warning: `--session` deletes every artifact in that session. Use `--dry-run` to preview.
</Warning>

<Warning>
  **`artifacta session seal --help`** — Warning: Sealing is irreversible. Sealed sessions cannot accept new artifacts.
</Warning>

## 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) |

<Info>
  **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.
</Info>

```bash theme={null}
# 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

```bash theme={null}
# 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.