---
title: CLI reference
description: Every `pictograph` subcommand, mirroring the SDK 1:1. Install via `pip install 'pictograph[cli]'`.
section: Reference
order: 2
---
The `pictograph` CLI is a thin wrapper over the SDK with Rich-formatted
output. Same operations, same auth model, no learning curve.

## Install

```bash
pip install 'pictograph[cli]'
```

## Auth

```bash
pictograph login                # interactive; writes ~/.pictograph/config.toml
# OR
export PICTOGRAPH_API_KEY=pk_live_…
# OR
pictograph datasets list --api-key pk_live_…
```

Resolution order: `--api-key` flag > `PICTOGRAPH_API_KEY` env > `~/.pictograph/config.toml`.

## Global flags

| Flag | Notes |
|---|---|
| `--version` / `-V` | Print version and exit |
| `--help` | Print help (works on every subcommand) |
| `--api-key <key>` | Override the resolved key |
| `--json` | Emit raw JSON instead of Rich tables (where applicable) |

## Top-level commands

```bash
pictograph init                  # drop AGENTS.md template into ./
pictograph login                 # save API key
```

## datasets

```bash
pictograph datasets list                                    # list (table)
pictograph datasets list --json                             # list (JSON)
pictograph datasets get road-signs                          # by name
pictograph datasets get road-signs --include-images         # with image summaries
pictograph datasets create new-dataset -d "Description"
pictograph datasets delete road-signs                       # confirms first
pictograph datasets delete road-signs --yes                 # skip confirm
pictograph datasets download road-signs -o ./dump --workers 10
```

## images

```bash
pictograph images upload <dataset> ./photo.jpg --folder /cars
pictograph images download <image-uuid> -o ./out.jpg
pictograph images delete <image-uuid> --yes
```

## annotations

```bash
pictograph annotations get <image-uuid>
pictograph annotations save <image-uuid> --file ./anns.json   # JSON list of annotations
pictograph annotations delete <image-uuid> --yes
```

## train

```bash
pictograph train start <dataset> --pipeline yolox --gpu a10g
pictograph train start <dataset> --pipeline detectron2 \
    --gpu a100 --config '{"epochs": 50}'
pictograph train status <run-uuid>
pictograph train cancel <run-uuid> --yes
pictograph train logs <run-uuid>          # current status (SSE streaming arrives in v1.1)
```

## models

```bash
pictograph models list
pictograph models download <model-uuid> -o ./yolox.onnx
```

## credits

```bash
pictograph credits balance
pictograph credits balance --json
pictograph credits history --limit 100
pictograph credits estimate training_a10g_per_minute -q 30
```

## agents

```bash
pictograph agents list-tools                               # see all 28 tools
pictograph agents export-tools -o tools.json               # JSON Schema dump
pictograph agents install-skill --target claude-code       # → ~/.claude/skills/pictograph-cv/
pictograph agents install-skill --target claude-ai         # → ./pictograph-cv.zip
pictograph agents install-skill --target both
```

## Examples

### Build + download a YOLO export

```bash
pictograph datasets create road-signs
# … upload images via the SDK or web app …
pictograph train start road-signs --pipeline yolox
# … wait for completion …
pictograph train status <run-uuid>
pictograph models download <model-uuid> -o ./yolox.onnx
```

### Bulk-export all completed datasets to COCO

```bash
for ds in $(pictograph datasets list --json | jq -r '.[].name'); do
  pictograph train start "$ds" --pipeline detectron2 --no-wait
done
```

(Use the SDK's `client.exports.create(..., format="coco")` directly for
better control — the CLI doesn't yet have an `export` subcommand; coming in v1.1.)

### Daily cost monitoring

```bash
pictograph credits balance --json | jq '.credits_remaining'
```

## Output

- **Default**: Rich tables for human-readable terminal use. Auto-detects
  TTY width and wraps gracefully.
- **`--json`**: pretty-printed JSON for piping into `jq` / scripting.
  Same payload structure as the SDK's `model_dump(mode="json")`.

## Errors

CLI errors print bold-red to stderr and exit with non-zero status. The
SDK's exception name maps to the message:

```
$ pictograph datasets get nonexistent
error: Project 'nonexistent' not found
$ echo $?
1
```

Exit codes:

| Code | Meaning |
|---|---|
| `0` | success |
| `1` | API error (handled cleanly by the CLI) |
| `2` | usage / config error (missing args, no API key) |

## See also

- [Quick Start](/docs/quick-start.md) — install + first run
- [Authentication](/docs/authentication.md) — key resolution + roles
- [Error handling](/docs/error-handling.md) — exception hierarchy