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

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

```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

# 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_TELEMETRY`  | —                          | Set to `1` to enable Sentry error reporting (opt-in)        |

<Info>
  **Agent integration pattern:** An orchestrator sets `ARTIFACTA_SESSION_ID` once in the environment. Every sub-agent inherits it automatically — zero flag passing required.
</Info>

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

```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
```