Managing Outputs¶

The tracker outputs subgroup inspects and manages the S3 outputs that a workflow run published. Two flavors of operation:

Tracker-managed: tracker outputs delete enqueues a server-side job that deletes S3 files and updates tracker's index in one step.
Hand-managed: tracker outputs update-db ... reflects S3 changes you made yourself (via aws s3 or S3 Batch Operations) into tracker's index. No S3 mutations happen.

Look up a run by S3 URL¶

tracker outputs info s3://bucket/runs/foo/sample.bam
tracker outputs info s3://bucket/runs/foo/

Returns the workflow run(s) whose Output.destination matches the URL as a substring (case-insensitive). Works for full file URLs and rundir prefixes alike.

foo-run-001  id=550e8400-e29b-41d4-a716-446655440000

Delete a run's outputs¶

tracker outputs delete RUN_NAME [--wait]

Enqueues a server-side job that deletes every S3 object under the run's output_dir and sets outputs_deleted_at on the run. The CLI returns immediately with a job_id; pass --wait to block until the job reaches a terminal state.

Enqueued delete job 7f3e... for 'foo-run-001' (enqueued).
Check progress: tracker outputs job-status 7f3e...

Authorization: You must be the run's owner, a cluster admin for the run's cluster, or a global admin.

Idempotent: if the outputs are already marked deleted, the command is a no-op. If a delete job is already running for the same run, delete returns the existing job id rather than starting a new one.

Exit codes (with --wait):

Code	Meaning
`0`	Job succeeded
`1`	Job failed, or authentication/permission error
`124`	Timed out before the job finished

Check the status of a lifecycle job¶

tracker outputs job-status JOB_ID

Inspects an async lifecycle job (e.g., the delete_outputs job created by tracker outputs delete). Useful to poll progress without --wait, or to look up an old job by id. Prints a one-line summary plus extras for finished delete_outputs jobs:

delete_outputs  succeeded  (id=7f3e...)
  run_id: 550e8400-e29b-41d4-a716-446655440000
  started: 2026-05-13T19:02:11Z
  completed: 2026-05-13T19:03:47Z
  objects deleted: 1842
  bytes deleted: 9876543210

Exit codes:

Code	Meaning
`0`	Job found
`1`	Job not found, or authentication / server error

Update tracker's index for hand-managed S3¶

Use these commands when you've already moved or deleted files in S3 and want tracker's record to match. They never touch S3.

Mark outputs as deleted (no S3 mutation)¶

tracker outputs update-db deleted RUN_NAME

Sets outputs_deleted_at on the run. Idempotent.

Rewrite output paths after a manual move¶

tracker outputs update-db moved RUN_NAME s3://new/prefix/

Rewrites every Output.destination row whose current destination sits under the run's output_dir, replacing the old prefix with s3://new/prefix/, and updates the run's output_dir itself. The destination prefix must be an s3:// URI ending with /.

Updated 'foo-run-001': 1842 output rows rewritten.
  source: s3://old-bucket/runs/foo-run-001/
  dest:   s3://new-bucket/archive/foo-run-001/

Refuses to operate on a run whose outputs are already marked deleted.