tofupilot runs

The runs command manages test Runs via the REST API, and every subcommand accepts --json.

ls

The ls subcommand lists and filters runs, and it supports filters by procedure, serial, outcome, time window, operator, station, batch, part, revision, and metadata. Pagination uses --limit and --cursor.

tofupilot runs ls --procedure-ids proc_abc --outcomes PASS --limit 50

The full filter list is: --search-query, --ids, --outcomes, --procedure-ids, --procedure-versions, --serial-numbers, --samples, --part-numbers, --revision-numbers, --batch-numbers, --duration-min, --duration-max, --started-after, --started-before, --ended-after, --ended-before, --created-after, --created-before, --created-by-user-ids, --created-by-station-ids, --operated-by-ids, --limit, --cursor, --sort-by, --sort-order, --metadata, and --include-metadata.

get

The get subcommand fetches a single run by ID.

tofupilot runs get --id run_abc123

create

The create subcommand creates a run. Required flags are --outcome, --procedure-id, --started-at, --ended-at, and --serial-number. Optional flags are --deployment-id, --procedure-version, --operated-by, --part-number, --revision-number, --batch-number, --sub-units, --docstring, --phases (JSON), --logs (JSON), --metadata (JSON), and --unit-metadata (JSON).

tofupilot runs create \
  --outcome PASS \
  --procedure-id proc_abc \
  --serial-number SN-0001 \
  --started-at 2026-05-19T08:00:00Z \
  --ended-at 2026-05-19T08:00:42Z

update

The update subcommand updates a run by ID, and it currently supports attaching uploads via --attachments.

tofupilot runs update --id run_abc --attachments att_1 att_2

update-metadata

The update-metadata subcommand PATCH-upserts custom metadata on a run, and you can pass null as a value to delete a key.

tofupilot runs update-metadata --id run_abc --metadata '{"shift":"A","temp":23.4}'

create-attachment

The create-attachment subcommand initializes a file attachment on a run, and it returns an upload URL that you pair with tofupilot attachments finalize after uploading bytes.

tofupilot runs create-attachment --id run_abc --name report.pdf

rm

The rm subcommand deletes one or more runs by ID.

tofupilot runs rm --ids run_a run_b