CLI reference

Every `pictograph` subcommand, mirroring the SDK 1:1. Install via `pip install 'pictograph[cli]'`.

The pictograph CLI is a thin wrapper over the SDK with Rich-formatted output. Same operations, same auth model, no learning curve.

Install

pip install 'pictograph[cli]'

Auth

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

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

datasets

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

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

annotations

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

train

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

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

credits

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

agents

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

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

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

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)