CLI

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, same vocabulary. It is also how a coding agent drives Pictograph: with the pictograph-cv skill installed (or an AGENTS.md from pictograph init), Claude Code or Codex runs these commands for you. See Agents.

pip install 'pictograph[cli]'
pictograph login                # interactive; writes ~/.pictograph/config.toml
pictograph datasets list

Auth resolves --api-key flag, then PICTOGRAPH_API_KEY, then ~/.pictograph/config.toml. --api-key, --json and --yes are per-command options, not global: write pictograph datasets list --json.

--version / -V is the only root-level flag. Every command takes --help.

Datasets, images, models, deployments, workflows and webhooks are addressed by name; a UUID works anywhere a name does.

Source: cli/commands/init.py · cli/commands/login.py

pictograph init                  # drop an AGENTS.md template into ./
pictograph login                 # save an API key (input hidden)

datasets

Source: cli/commands/datasets.py

pictograph datasets list --json
pictograph datasets get road-signs --include-images
pictograph datasets insights road-signs                     # class balance, stages, dimensions
pictograph datasets duplicates road-signs -t 0.94           # near-duplicate clusters
pictograph datasets create road-signs -d "Description" -t bbox
pictograph datasets update road-signs --new-name renamed
pictograph datasets archive road-signs                      # hide from the default list
pictograph datasets unarchive road-signs
pictograph datasets delete road-signs --yes
pictograph datasets download road-signs -o ./dump -w 10     # images + annotations
pictograph datasets export road-signs --format coco -o ./exports   # -o is a DIRECTORY
pictograph datasets import-coco road-signs ./instances.json
pictograph datasets storage road-signs                      # cold-storage state + restore quote
pictograph datasets freeze road-signs                       # cold storage (free)
pictograph datasets restore road-signs                      # charges compute credits

images

Source: cli/commands/images.py

Every per-image command takes the dataset first, then the filename.

pictograph images list road-signs --directory /train --status complete
pictograph images list road-signs --split val --min-confidence-lt 0.4   # active learning
pictograph images upload road-signs ./photo.jpg --directory /cars
pictograph images bulk-upload road-signs ./a.jpg ./b.jpg --directory /cars
pictograph images upload-directory road-signs ./photos      # recreates the subdirectory tree
pictograph images get road-signs 001.jpg
pictograph images download road-signs 001.jpg -o ./out.jpg
pictograph images delete road-signs 001.jpg --yes           # --archive to soft-delete
pictograph images tag road-signs <image-uuid> -t blurry     # UUIDs; --remove to strip
pictograph images review road-signs 001.jpg                 # approve -> complete
pictograph images review road-signs 001.jpg --request-changes -n "fix bbox"
pictograph images split road-signs 001.jpg train            # train | val | test | none
pictograph images rebalance <dataset-uuid> --train 80 --val 10 --test 10

annotations

Source: cli/commands/annotations.py

pictograph annotations get road-signs 001.jpg
pictograph annotations save road-signs 001.jpg -f ./anns.json   # JSON list, full overwrite
pictograph annotations bulk-save -f ./many.json                 # {"image-uuid": [...]}
pictograph annotations delete road-signs 001.jpg --yes
pictograph annotations rename-class road-signs car vehicle --yes
pictograph annotations merge-class road-signs van truck --yes   # reassign, then drop `van`
pictograph annotations delete-class road-signs van --with-annotations --yes

auto-annotate

Source: cli/commands/auto_annotate.py

pictograph auto-annotate point road-signs 001.jpg --x 120 --y 90 --name sign
pictograph auto-annotate box road-signs 001.jpg --box 10,20,200,150 --name sign
pictograph auto-annotate text road-signs 001.jpg --prompt "stop sign"
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 batch road-signs --images a.jpg,b.jpg --model "Shelf Detector"
pictograph auto-annotate quote --dataset road-signs --images a.jpg,b.jpg \
    --classes "person:bbox"                                  # price it without running
pictograph auto-annotate get <job-uuid>
pictograph auto-annotate cancel-batch <job-uuid> --yes

quote --frames N prices images that do not exist yet, which is what you want before cutting a video into frames.

train

Source: cli/commands/train.py

A run trains a completed export, so start takes the dataset and the export name.

pictograph train start road-signs road-signs-v1 --pipeline yolox --gpu a10g
pictograph train start road-signs road-signs-v1 --pipeline rfdetr_segmentation \
    --gpu a100 --config '{"epochs": 50}'
pictograph train list --status running
pictograph train status <run-uuid>
pictograph train wait <run-uuid> --timeout 7200
pictograph train cancel <run-uuid> --yes
pictograph train cancel-batch <run-uuid> <run-uuid> --yes

augment

Source: cli/commands/augment.py

pictograph augment ops                                       # every op and its flag
pictograph augment dataset road-signs --into road-signs-aug \
    --multiplier 3 --flip --rotate 15 --brightness 0.2
pictograph augment dataset road-signs --grayscale --blur 2 \
    --crop 0.8 --resize 640x480 --seed 42                    # --seed for reproducibility

tile

Source: cli/commands/tile.py

pictograph tile dataset aerial --into aerial-tiled -r 2 -c 2
pictograph tile dataset aerial --into aerial-tiled \
    -r 3 -c 3 --overlap 0.1 --exclude-empty

models

Source: cli/commands/models.py

pictograph models list
pictograph models get "Shelf Detector"
pictograph models update "Shelf Detector" --name "Signs v2" --visibility public
pictograph models download "Shelf Detector" -o ./yolox.onnx -f onnx
pictograph models predict "Shelf Detector" ./photo.jpg       # local; needs [inference]
pictograph models predict "Shelf Detector" ./photo.jpg --remote   # on Pictograph; free, one image
pictograph models predict "Shelf Detector" 'frames/*.jpg' https://example.com/a.jpg   # several: JSON Lines
curl -s https://example.com/a.jpg | pictograph models predict "Shelf Detector" - --remote --json
pictograph models fork <organization> <model> --name "Ours"   # import a public model
pictograph models delete "Shelf Detector" --yes              # admin/owner

-f accepts onnx (default), pytorch, safetensors, pte or engine. A format the model does not publish is refused, never substituted.

predict takes one or more images. Each is a file path, a glob (quote it, and the CLI expands it, the same in every shell), an http(s) URL fetched on your machine, or - for image bytes on stdin. A path that exists is always that file, even when its name contains [, * or ?. With more than one image, or with --jsonl, it prints one JSON object per line as each image finishes:

{"input": "frames/0001.jpg", "result": {"model_type": "object_detection", "predictions": []}}
{"input": "https://example.com/a.jpg", "error": "Could not fetch the image ...", "error_type": "ValueError"}

One image that fails does not stop the rest, and the exit code is 1 when any failed. A pattern that matches nothing, or a path that does not exist, stops the command before anything runs. --top-k sets how many classes a classification model returns. deployments predict reads the same inputs.

metrics

Source: cli/commands/metrics.py

Offline detection evaluation: no network call, no credits. Both files are Pictograph JSON mapping an image key to its annotations ({"img.jpg": [{…, "confidence": 0.8}]}). Handy in CI to fail a build when mAP drops.

pictograph metrics evaluate preds.json ground_truth.json --iou 0.5   # P/R/F1 + mAP

deployments

Source: cli/commands/deployments.py

pictograph deployments list
pictograph deployments get "prod-detector"
pictograph deployments compute-options                       # tiers + per-minute rate
pictograph deployments quote --gpu t4 --min-containers 0
pictograph deployments create "Shelf Detector" --name prod --gpu t4   # one-time token
pictograph deployments predict "prod-detector" ./photo.jpg --token pk_deploy_...
pictograph deployments predict "prod-detector" 'frames/*.jpg' --token pk_deploy_...   # JSON Lines
pictograph deployments pause "prod-detector"                 # stops compute + billing
pictograph deployments resume "prod-detector"
pictograph deployments delete "prod-detector" --yes

Pass --endpoint https://…/predict to predict and the pk_deploy_ token becomes the only credential needed, with no account API key.

workflows

Source: cli/commands/workflows.py

pictograph workflows list
pictograph workflows get "gate-crossings"
pictograph workflows create gate-crossings -g ./graph.json
pictograph workflows update "gate-crossings" -g ./graph.json # graph / name / readme / status
pictograph workflows run "gate-crossings"                    # waits unless --no-wait
pictograph workflows run-status <run-uuid>
pictograph workflows cancel <run-uuid> --yes                 # free: cancelled runs are never charged
pictograph workflows delete "gate-crossings" --yes

exports

Source: cli/commands/exports.py

pictograph exports list --dataset road-signs --status completed
pictograph exports create road-signs --name v1 -f coco       # waits unless --no-wait
pictograph exports create road-signs --name v1 -f yolo \
    --include-images --organize-by-split                     # directly-trainable layout
pictograph exports get road-signs v1
pictograph exports download road-signs v1 -o ./out.zip
pictograph exports get-by-id <export-uuid>
pictograph exports download-by-id <export-uuid> -o ./out.zip
pictograph exports delete road-signs v1 --yes                # admin/owner
pictograph exports bulk-delete <export-uuid> <export-uuid> --yes

connectors

Source: cli/commands/connectors.py

export PICTOGRAPH_SOURCE_KEY=…            # the SOURCE provider's key, not yours
pictograph connectors validate v7                            # list importable datasets
pictograph connectors check-limits --images 500 --bytes 100000000
pictograph connectors import v7 -d <source-dataset-id>       # waits unless --no-wait
pictograph connectors status <import-id>
pictograph connectors cancel <import-id>                     # keeps imported images

Pass the source key by environment variable: a key on the command line lands in shell history and is readable by any user via ps.

search

Source: cli/commands/search.py

pictograph search similar road-signs 001.jpg -n 20 -t 0.6    # visual similarity
pictograph search tags --dataset road-signs --object car     # --object/--scene/--attribute

video

Source: cli/commands/video.py

pictograph video upload ./clip.mp4                           # prints the stored path
pictograph video probe <stored-path>                         # duration / fps / dimensions
pictograph video extract-frames road-signs <stored-path> \
    --directory-name frames --sample-fps 1                   # waits unless --no-wait
pictograph video status <job-uuid>

organizations

Source: cli/commands/organizations.py

pictograph organizations me                                  # tier, credits, member cap
pictograph organizations update --name "New Name" --public
pictograph organizations members
pictograph organizations member-role <membership-uuid> --role admin
pictograph organizations member-remove <membership-uuid> --yes
pictograph organizations invites --status pending
pictograph organizations invite teammate@example.com --role member
pictograph organizations invite-revoke <invite-uuid>

member-role and member-remove take the membership UUID printed by members.

webhooks

Source: cli/commands/webhooks.py

pictograph webhooks event-types                              # subscribable events
pictograph webhooks create https://example.com/hook -e workflow.run.completed
pictograph webhooks list
pictograph webhooks get https://example.com/hook
pictograph webhooks update https://example.com/hook --disabled
pictograph webhooks rotate-secret https://example.com/hook   # new secret, printed once
pictograph webhooks test https://example.com/hook            # synthetic signed event
pictograph webhooks deliveries --endpoint https://example.com/hook --status failed
pictograph webhooks replay <delivery-uuid>
pictograph webhooks delete https://example.com/hook --yes

create and rotate-secret print the signing secret once.

directories

Source: cli/commands/directories.py

pictograph directories list road-signs --parent /train       # direct children
pictograph directories tree road-signs
pictograph directories stats road-signs /train               # counts incl. subdirectories
pictograph directories create road-signs /train/positive     # parents auto-created
pictograph directories rename road-signs /train/old new      # NEW_NAME is one segment
pictograph directories delete road-signs /train/old --cascade --yes

--cascade moves the directory’s images up to its parent, then deletes it.

tasks

Source: cli/commands/tasks.py

pictograph tasks list --limit 25
pictograph tasks list --all --max-total 500                  # auto-page every task
pictograph tasks contributions <task-id>                     # per-annotator breakdown
pictograph tasks contributions <task-id> --json

contributions prints who annotated how many images, active editing time, and annotations authored - the same numbers the app’s task modal shows.

notifications

Source: cli/commands/notifications.py

pictograph notifications list --unread
pictograph notifications unread-count
pictograph notifications read <notification-id>
pictograph notifications read-all
pictograph notifications delete <notification-id>

credits

Source: cli/commands/credits.py

pictograph credits balance --json
pictograph credits history --all --max-total 5000            # auto-page the ledger
pictograph credits usage -r week                             # day / week / month / all
pictograph credits estimate training_a10g -q 30

tools

Source: cli/commands/tools.py

Your organization’s vision tools - SAM3, each ready model, each active deployment, each workflow - and how to call each one. List, describe, then run.

pictograph tools list                                        # every tool you can call
pictograph tools list --kind workflow --json
pictograph tools describe sam3                               # the card, as Markdown
pictograph tools describe "model/Shelf Detector" --json      # the card, for an agent
pictograph tools describe "workflow/Door counter"

A card says which inputs each way of running the tool accepts (file, URL, bytes, video, dataset), its parameters, what one prediction looks like, the exact CLI, Python and HTTP call, and what each costs. See Vision tools.

agents

Source: cli/commands/agents.py

pictograph agents list-tools                                 # all 37 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

Recipes

# Build, train, download.
pictograph exports create road-signs --name v1 -f pictograph --include-images
pictograph train start road-signs v1 --pipeline yolox
pictograph models download "road-signs-detector" -o ./yolox.onnx

# Nightly COCO export of every dataset.
for ds in $(pictograph datasets list --json | jq -r '.[].name'); do
  pictograph exports create "$ds" --name nightly -f coco --no-wait
done

# Remaining included allowance this period, in dollars.
pictograph credits balance --json | jq '.included_remaining_micro_usd / 1000000'

Output and exit codes

Default output is a Rich table sized to your terminal; --json emits the same payload as the SDK’s model_dump(mode="json"), ready for jq. Errors print bold-red to stderr.

Code	Meaning
`0`	success
`1`	API error
`2`	usage / config error (missing args, no API key)

CLI

init / login