CLI

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

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.

init / login

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   # runs on our GPUs
pictograph models fork <organization> <model>          # fork 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.

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 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 run "gate-crossings"                    # waits unless --no-wait
pictograph workflows run-status <run-uuid>
pictograph workflows cancel <run-uuid> --yes                 # refunds the deposit
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

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)

See also

• Quick start - install and first run
• Authentication - key resolution and roles
• Error handling - the exception hierarchy behind the exit codes