CLI reference

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

The CLI mirrors the SDK 1:1 — every resource group below maps to a client.<group> resource. --json (where applicable), --api-key, and --yes (skip confirm on destructive ops) work consistently across groups.

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 insights road-signs                     # health check: class balance, stages, dimensions
pictograph datasets insights road-signs --json              # raw insights JSON
pictograph datasets create new-dataset -d "Description" -t bbox
pictograph datasets update road-signs --new-name renamed    # rename / describe / retype
pictograph datasets archive road-signs                      # hide from the default list (reversible)
pictograph datasets unarchive road-signs
pictograph datasets duplicates road-signs -t 0.94           # near-duplicate clusters (by name)
pictograph datasets delete road-signs --yes                 # --yes skips confirm
pictograph datasets download road-signs -o ./dump --workers 10
pictograph datasets storage road-signs                      # cold-storage state + restore quote
pictograph datasets freeze road-signs                       # move to cold storage (free)
pictograph datasets restore road-signs                      # restore (charges compute credits)

images

pictograph images list <dataset> --folder /train --status complete  # list images (JSON)
pictograph images upload <dataset> ./photo.jpg --folder /cars
pictograph images get <image-uuid>                          # metadata JSON
pictograph images download <image-uuid> -o ./out.jpg
pictograph images delete <image-uuid> --yes
pictograph images review <image-uuid>                         # approve → complete
pictograph images review <image-uuid> --request-changes -n "fix bbox"  # → annotate
pictograph images split <image-uuid> train                    # assign train/val/test split
pictograph images rebalance <dataset> --train 80 --val 10 --test 10  # one-click ratio split
pictograph images list <dataset> --split val                  # filter by split

annotations

pictograph annotations get <image-uuid>
pictograph annotations save <image-uuid> --file ./anns.json   # JSON list — full overwrite
pictograph annotations delete <image-uuid> --yes
pictograph annotations rename-class <dataset> car vehicle --yes  # ontology + all annotations

auto-annotate

pictograph auto-annotate point road-signs sign.jpg --x 120 --y 90 --name sign  # SAM3 point → polygon
pictograph auto-annotate box road-signs sign.jpg --box 10,20,200,150 --name sign  # box → bbox (+polygon)
pictograph auto-annotate text road-signs sign.jpg --prompt "stop sign"         # phrase grounding
pictograph auto-annotate batch road-signs --images a.jpg,b.jpg \
    --classes "person:bbox,car:polygon" --confidence 0.5      # waits unless --no-wait
pictograph auto-annotate get <job-uuid>                       # batch job status
pictograph auto-annotate cancel-batch <job-uuid> --yes

train

pictograph train start <dataset> --pipeline yolox --gpu a10g
pictograph train start <dataset> --pipeline rfdetr_segmentation \
    --gpu a100 --config '{"epochs": 50}'
pictograph train list --status running                        # list runs (filterable)
pictograph train status <run-uuid>
pictograph train wait <run-uuid> --timeout 7200               # block until terminal
pictograph train cancel <run-uuid> --yes
pictograph train logs <run-uuid>          # current status (SSE streaming arrives in v1.1)

augment

pictograph augment ops                                        # list every augmentation flag
pictograph augment dataset road-signs --into road-signs-aug \
    --multiplier 3 --flip --rotate 15 --brightness 0.2        # generate an augmented version
pictograph augment dataset road-signs --grayscale --blur 2 \
    --crop 0.8 --resize 640x480 --seed 42                     # more ops; --seed for reproducibility

tile

pictograph tile dataset aerial --into aerial-tiled \
    --rows 2 --cols 2                                         # slice each image into a 2×2 grid
pictograph tile dataset aerial --into aerial-tiled \
    --rows 3 --cols 3 --overlap 0.1 --exclude-empty           # 3×3 with overlap, drop empty tiles

models

pictograph models list
pictograph models get <model-name-or-uuid>                    # name (org-unique) or UUID
pictograph models update <model-name-or-uuid> --name "Signs v2" --visibility public
pictograph models download <model-name-or-uuid> -o ./yolox.onnx
pictograph models fork <public-model-uuid>                    # import into your org (source UUID)
pictograph models delete <model-name-or-uuid> --yes           # admin/owner only

metrics

Offline detection evaluation + active-learning ranking — no server round-trip, no credits. Reads Pictograph-JSON files mapping an image key to its annotations ({"img.jpg": [{…, "confidence": 0.8}], …}); handy in CI to fail a build when mAP drops, or to prioritize which images to label next.

pictograph metrics evaluate preds.json ground_truth.json --iou 0.5   # P/R/F1 + mAP
pictograph metrics evaluate preds.json ground_truth.json --json      # machine-readable
pictograph metrics rank preds.json --top 20                          # review queue, most-uncertain first
pictograph metrics rank preds.json --method entropy --json           # least_confidence|min_confidence|margin|entropy

deployments

pictograph deployments list
pictograph deployments get <deployment-uuid>
pictograph deployments create <model-uuid> --name prod        # prints a one-time token
pictograph deployments predict <deployment-uuid> ./photo.jpg --token pk_deploy_…
pictograph deployments pause <deployment-uuid>                # stops compute + billing
pictograph deployments resume <deployment-uuid>
pictograph deployments delete <deployment-uuid> --yes

workflows

pictograph workflows list
pictograph workflows get <workflow-uuid>
pictograph workflows create --file ./graph.json
pictograph workflows run <workflow-uuid>                      # waits unless --no-wait
pictograph workflows run-status <run-uuid>
pictograph workflows cancel <run-uuid>                        # refunds the deposit
pictograph workflows delete <workflow-uuid> --yes

exports

pictograph exports list
pictograph exports get <dataset> <export-name>
pictograph exports create <dataset> --format coco --name v1   # waits unless --no-wait
pictograph exports create <dataset> --format yolo --name v1 --include-images --organize-by-split  # train/valid/test ZIP
pictograph exports download <dataset> <export-name> -o ./out.zip
pictograph exports delete <dataset> <export-name> --yes       # admin/owner only

connectors

pictograph connectors validate v7 --key <src-key>             # list importable datasets
pictograph connectors check-limits --images 500 --bytes 100000000
pictograph connectors import v7 --key <src-key> --dataset ds1  # waits unless --no-wait
pictograph connectors status <import-id>
pictograph connectors cancel <import-id>                      # keeps already-imported images

search

pictograph search similar <image-uuid> --limit 20 -t 0.6      # SigLIP visual similarity
pictograph search tags --dataset road-signs --object car      # auto-tag search (--object/--scene/--attribute)

video

pictograph video upload ./clip.mp4                            # prints the gcs_path
pictograph video probe <gcs-path>                             # duration / fps / dims
pictograph video extract-frames <dataset> <gcs-path> \
    --folder-name frames --sample-fps 1                       # waits unless --no-wait
pictograph video status <job-uuid>

organizations

pictograph organizations me                                   # tier, credits, member cap
pictograph organizations members
pictograph organizations member-role <user-uuid> --role admin # admin/owner only
pictograph organizations member-remove <user-uuid> --yes
pictograph organizations invites --status pending
pictograph organizations invite teammate@example.com --role member
pictograph organizations invite-revoke <invite-uuid>

webhooks

pictograph webhooks create https://example.com/hook -e workflow.run.completed  # prints the secret once
pictograph webhooks list
pictograph webhooks get <endpoint-uuid>
pictograph webhooks test <endpoint-uuid>                      # send a synthetic signed event
pictograph webhooks deliveries --endpoint <endpoint-uuid>
pictograph webhooks replay <delivery-uuid>                    # re-queue a failed delivery
pictograph webhooks delete <endpoint-uuid> --yes

credits

pictograph credits balance
pictograph credits balance --json
pictograph credits history --limit 100
pictograph credits history --all --max-total 5000             # auto-page the whole ledger
pictograph credits estimate training_a10g -q 30

agents

pictograph agents list-tools                               # see all 32 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-name-or-uuid> -o ./yolox.onnx

Bulk-export all completed datasets to COCO

for ds in $(pictograph datasets list --json | jq -r '.[].name'); do
  pictograph exports create "$ds" --format coco --name nightly --no-wait
done

Daily cost monitoring

# Remaining included compute allowance this period, in dollars (µUSD ÷ 1e6)
pictograph credits balance --json | jq '.included_remaining_micro_usd / 1000000'

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 — install + first run
• Authentication — key resolution + roles
• Error handling — exception hierarchy