Depot CLI: Depot CI commands reference

Reference for all depot ci commands. To install the Depot CLI, see Installation.

Other Depot product CLI references:

• CLI overview and platform commands
• Container builds commands
• Agents commands

depot ci migrate

Migrates GitHub Actions workflows to Depot CI. The command runs two phases: it validates your environment with a preflight check, then copies and transforms your selected workflows into .depot/workflows/.

depot ci migrate

After migration, the command reports any secrets and variables referenced by the migrated workflows and directs you to depot ci migrate secrets-and-vars for importing them.

Each phase is also available as a standalone subcommand:

• depot ci migrate preflight — validate authentication and GitHub app access
• depot ci migrate workflows — copy and transform workflows
• depot ci migrate secrets-and-vars — import GitHub secrets and variables into Depot CI

Flags

depot ci migrate preflight

Validates that you are authenticated, detects the GitHub repository from your git remote, and checks that the Depot Code Access GitHub App is installed with the correct permissions and repository access.

depot ci migrate preflight

If the app is not installed or needs updated permissions, the command prints a link to configure it.

Flags

depot ci migrate workflows

Copies workflows from .github/workflows/ into .depot/workflows/, applying Depot CI compatibility transformations and inline comments documenting any changes.

depot ci migrate workflows

What depot ci migrate workflows does

1. Discovers all workflow files in .github/workflows/.
2. Analyzes each workflow for compatibility with Depot CI.
3. Prompts you to select which workflows to migrate.
4. Copies selected workflows to .depot/workflows/ and any local actions from .github/actions/ to .depot/actions/.
5. Applies compatibility fixes (for example, mapping ubuntu-latest to depot-ubuntu-latest).
6. Disables jobs that use unsupported features and adds inline comments explaining what changed.
7. Reports any secrets and variables detected in the migrated workflows.

What gets copied

Flags

What gets transformed

The command applies three kinds of changes to migrated workflows, documented with inline comments:

• runs-on labels are remapped from GitHub runner labels (like ubuntu-latest) to their Depot equivalents.
• Unsupported triggers (like release or schedule) are removed from the on: block with a comment explaining why.
• Jobs with unsupported features are commented out entirely, with a DISABLED comment noting the reason.
• .github/ path references in copied workflow and action files are rewritten to their .depot/ equivalents.

Each migrated file includes a header comment listing the source workflow and a summary of all changes made. For the full compatibility matrix, see Compatibility with GitHub Actions.

depot ci migrate secrets-and-vars

Creates a one-shot GitHub Actions workflow that reads secrets and variables from your GitHub repository and imports them into Depot CI.

depot ci migrate secrets-and-vars

The command pushes a temporary branch to your GitHub repository containing a workflow that runs on GitHub Actions. The workflow reads your existing GitHub secrets and variables and imports them into Depot CI using the Depot CLI.

In interactive mode, you can preview the generated workflow before it is created. After the workflow is triggered, the command prints a URL where you can monitor the import.

Flags

depot ci run

Submits a workflow to Depot CI and starts a run against your local working tree, without requiring a push to GitHub first. It's the fastest way to test a workflow against changes you're actively working on.

depot ci run --workflow .depot/workflows/ci.yml

If you have local changes relative to your branch's remote state, the CLI automatically detects them, uploads a patch to Depot Cache, and injects a patch-application step after actions/checkout in each selected job. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch.

Flags

Run specific jobs

Pass --job one or more times to run a subset of jobs defined in the workflow:

depot ci run --workflow .depot/workflows/ci.yml --job build --job test

Jobs not listed are excluded from the submitted workflow. If a requested job name does not exist in the workflow, the command exits with an error listing the available jobs.

Debug with SSH

Use --ssh to start the run and immediately connect to the job's sandbox via an interactive terminal:

depot ci run --workflow .depot/workflows/ci.yml --job build --ssh

Use --ssh-after-step to insert a tmate debug session after a specific step in a single job. This lets you SSH into the runner at that point in the workflow to inspect state interactively.

depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3

Both --ssh and --ssh-after-step require exactly one --job to be specified.

What depot ci run does

When you run depot ci run with local changes, the CLI automatically detects the changes and uploads a patch. For any job that has an actions/checkout step, the CLI injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch.

Each time you run depot ci run locally, the CLI uploads a fresh patch, so you can keep iterating until the workflow passes.

depot ci run list

Lists CI runs for your organization. By default returns the 50 most recent queued and running runs.

depot ci run list

Alias: depot ci run ls.

Flags

Examples

List failed runs:

depot ci run list --status failed

List failed runs for a pull request:

depot ci run list --repo depot/api --status failed --pr 42

List workflow dispatch runs:

depot ci run list --trigger workflow_dispatch

List finished and failed runs:

depot ci run list --status finished --status failed

List the 5 most recent runs:

depot ci run list -n 5

List runs as JSON:

depot ci run list --output json

JSON response:

[
  {
    "run_id": "<run-id>",
    "repo": "depot/demo-app",
    "trigger": "push",
    "sha": "abc123def456",
    "status": "finished",
    "created_at": "2026-04-23T14:30:45Z"
  }
]

The status field is a string: queued, running, finished, failed, or cancelled.

depot ci workflow

Manages CI workflows.

depot ci workflow list

Lists recent CI workflow runs for your organization. By default returns the 50 most recent.

depot ci workflow list

Alias: depot ci workflow ls.

Flags

Examples

List recent workflows:

depot ci workflow list

List the 5 most recent workflows:

depot ci workflow list -n 5

Filter by workflow name:

depot ci workflow list --name deploy

Filter workflows by repo, status, and SHA:

depot ci workflow list --repo depot/api --status failed --sha abc123

List workflows as JSON:

depot ci workflow list --output json

JSON response:

[
  {
    "workflow_id": "<workflow-id>",
    "name": "CI",
    "workflow_path": ".depot/workflows/ci.yml",
    "repo": "depot/api",
    "status": "finished",
    "trigger": "push",
    "run_id": "<run-id>",
    "sha": "<merge-sha>",
    "head_sha": "<head-sha>",
    "created_at": "2026-04-28T12:00:00Z",
    "job_counts": {
      "total": 5,
      "queued": 0,
      "waiting": 0,
      "running": 0,
      "finished": 5,
      "failed": 0,
      "cancelled": 0,
      "skipped": 0
    }
  }
]

The status field is a string: queued, running, finished, failed, or cancelled.

depot ci workflow show

Shows a CI workflow, including the parent run context, executions, jobs, and per-job attempt details.

depot ci workflow show <workflow-id>

Alias: depot ci workflow get.

Flags

Examples

Show a workflow:

depot ci workflow show <workflow-id>

The command prints:

• Org, repo, run ID with status, workflow ID with status, name, path, ref, SHA, and trigger.
• Each execution with its status, start time, finish time, and duration.
• Each job with its status and duration. For each job, the command shows the latest attempt's ID, status, sandbox ID, session ID, and a ready-to-run depot ci logs command. If the job has more than one attempt, all attempts are listed.

Show a workflow as JSON:

depot ci workflow show <workflow-id> --output json

JSON response:

{
  "org_id": "<org-id>",
  "run": {
    "run_id": "<run-id>",
    "repo": "depot/api",
    "ref": "refs/heads/main",
    "sha": "<merge-sha>",
    "head_sha": "<head-sha>",
    "trigger": "push",
    "status": "failed",
    "created_at": "2026-04-30T14:01:00Z",
    "started_at": "2026-04-30T14:02:00Z",
    "finished_at": "2026-04-30T14:25:15Z"
  },
  "workflow": {
    "workflow_id": "<workflow-id>",
    "name": "CI",
    "workflow_path": ".depot/workflows/ci.yml",
    "status": "failed",
    "error_message": "tests failed",
    "created_at": "2026-04-30T14:01:05Z",
    "started_at": "2026-04-30T14:02:11Z",
    "finished_at": "2026-04-30T14:25:15Z"
  },
  "executions": [...],
  "jobs": [...]
}

depot ci dispatch

Triggers a workflow via workflow_dispatch. Inputs are validated against the workflow's declared input schema, so required inputs must be supplied and typed inputs (boolean, number, choice) are coerced on the server.

depot ci dispatch --repo <owner/repo> --workflow <filename> --ref <branch-or-tag>

Note: --workflow takes the workflow file's basename (for example deploy.yml), not the full repo path .depot/workflows/deploy.yml.

Flags

Examples

Dispatch a workflow on the main branch

depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main

depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main --output json

JSON response:

{
  "org_id": "<org-id>",
  "run_id": "<run-id>"
}

Pass inputs

depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main \
  --input environment=staging --input dry_run=true

depot ci status

Looks up the status of a Depot CI run and displays its workflows, jobs, and individual job attempts in a hierarchical view.

depot ci status <run-id>

Replace <run-id> with the run ID returned by depot ci run or visible in the Depot dashboard. The command prints:

• The organization and run ID with the overall run status.
• Each workflow in the run, with its status and workflow file path.
• Each job within a workflow, with its job ID, key, and status.
• Each attempt within a job, with its attempt ID, attempt number, and status. Plus a ready-to-run depot ci logs command, a link to the attempt in the Depot dashboard, and (when applicable) depot ci ssh and log download commands.

Flags

Examples

Show the status as JSON

depot ci status <run-id> --output json

JSON response:

{
  "org_id": "<org-id>",
  "run_id": "<run-id>",
  "status": "running",
  "workflows": [
    {
      "workflow_id": "<workflow-id>",
      "status": "running",
      "workflow_path": ".depot/workflows/ci.yml",
      "name": "CI",
      "jobs": [
        {
          "job_id": "<job-id>",
          "job_key": "ci.yml:test",
          "status": "running",
          "attempts": [
            {
              "attempt_id": "<attempt-id>",
              "attempt": 1,
              "status": "running",
              "sandbox_id": "<sandbox-id>",
              "session_id": "<session-id>",
              "logs_command": "depot ci logs <attempt-id>",
              "download_available": false,
              "view_url": "https://depot.dev/orgs/<org-id>/workflows/<workflow-id>?job=<job-id>&attempt=<attempt-id>",
              "ssh_available": true,
              "ssh_command": "depot ci ssh <run-id> --job ci.yml:test"
            }
          ]
        }
      ]
    }
  ]
}

download_available becomes true and download_command appears once the attempt reaches finished status. ssh_available and ssh_command appear only while the attempt is running with a sandbox.

depot ci cancel

Cancels a queued or running workflow (all its jobs), or a single job within a workflow.

depot ci cancel <run-id> --workflow <workflow-id>
depot ci cancel <run-id> --job <job-id>

Exactly one of --workflow or --job must be provided; they are mutually exclusive. When you pass --job, the CLI looks up the containing workflow via the run's status, so you do not need to also pass --workflow.

Workflows and jobs that have already reached a terminal state (finished, failed, or cancelled) cannot be cancelled and will return an error.

Flags

Examples

Cancel an entire workflow (all jobs within it)

depot ci cancel <run-id> --workflow <workflow-id>

depot ci cancel <run-id> --workflow <workflow-id> --output json

JSON response:

{"workflow_id": "<workflow-id>", "status": "cancelled"}

Cancel a single job (workflow is resolved automatically)

depot ci cancel <run-id> --job <job-id>

depot ci cancel <run-id> --job <job-id> --output json

JSON response:

{"job_id": "<job-id>", "status": "cancelled"}

depot ci rerun

Re-runs every job in a workflow that has reached a terminal state. Creates a new attempt for each job.

depot ci rerun <run-id>

If the run contains multiple workflows, pass --workflow <id> to select one. When the run contains a single workflow, the CLI resolves it automatically. Rerunning a workflow that is still running returns a precondition error — cancel it first if you want to restart.

Flags

Examples

Rerun the workflow in a run

depot ci rerun <run-id>

depot ci rerun <run-id> --output json

JSON response:

{"workflow_id": "<workflow-id>", "job_count": 5}

Rerun a specific workflow in a multi-workflow run

depot ci rerun <run-id> --workflow <workflow-id>

depot ci rerun <run-id> --workflow <workflow-id> --output json

JSON response:

{"workflow_id": "<workflow-id>", "job_count": 5}

depot ci retry

Retries a single failed or cancelled job, or every failed and cancelled job in a workflow.

depot ci retry <run-id> --job <job-id>
depot ci retry <run-id> --failed

Requires exactly one of --job or --failed.

• --job <id> retries a single job. The workflow containing the job is resolved automatically from the run's status.
• --failed retries every failed/cancelled job in the workflow. If the run contains multiple workflows, pass --workflow <id>; otherwise the single workflow is resolved automatically.

Each retry creates a new attempt for the selected job(s); the previous attempts are preserved and visible in depot ci status.

Flags

Examples

Retry a single job

depot ci retry <run-id> --job <job-id>

depot ci retry <run-id> --job <job-id> --output json

JSON response:

{"job_id": "<job-id>", "attempt_id": "<attempt-id>", "attempt": 2, "status": "queued"}

Retry every failed and cancelled job in the only workflow

depot ci retry <run-id> --failed

depot ci retry <run-id> --failed --output json

JSON response:

{"workflow_id": "<workflow-id>", "job_ids": ["<job-id>", "..."], "job_count": 3}

Retry every failed and cancelled job in a specific workflow

depot ci retry <run-id> --failed --workflow <workflow-id>

depot ci retry <run-id> --failed --workflow <workflow-id> --output json

JSON response:

{"workflow_id": "<workflow-id>", "job_ids": ["<job-id>", "..."], "job_count": 3}

depot ci logs

Fetches and prints the log output for a CI job. Accepts a run ID, job ID, or attempt ID. When given a run or job ID, the command resolves to the latest attempt automatically. Use --job and --workflow to disambiguate when a run has multiple jobs.

depot ci logs <run-id | job-id | attempt-id>

Flags

Examples

Fetch logs by attempt ID

depot ci logs <attempt-id>

Fetch logs for the latest attempt of a run

depot ci logs <run-id>

Fetch logs for a specific job in a run

depot ci logs <run-id> --job test

Disambiguate when job names overlap across workflows

depot ci logs <run-id> --job build --workflow ci.yml

Follow live logs

depot ci logs <job-id> --follow

If you pass a run or job ID that hasn't started yet, the command waits up to 30 seconds for the run to create jobs and start the latest attempt, then streams logs as they arrive.

Prefix log lines with UTC timestamps

depot ci logs <attempt-id> --timestamps

Emit logs as newline-delimited JSON events

depot ci logs <attempt-id> --output json

The finite form emits one line event per log line, with timestamp, timestamp_ms, stream (stdout or stderr), step_key, step_id, step_name, line_number, and body.

Combine with --follow to stream the live attempt as JSON. The streaming form emits the same line events plus two additional event types:

depot ci logs <attempt-id> --follow --output json

• status: signals an attempt status change (for example, running, finished, failed).
• end: marks the end of the stream, with the final status and line_count.

Download logs to a file

depot ci logs <attempt-id> --output-file logs.txt

Use --output-file together with --output json to download a JSONL export:

depot ci logs <attempt-id> --output json --output-file logs.jsonl

--output-file doesn't work with --follow.

depot ci metrics

Fetches CPU and memory metrics for a CI job attempt, job, or run.

depot ci metrics <attempt-id>

When given an attempt ID, the command prints a summary of CPU and memory utilization for that attempt. To inspect every attempt of a job or every job in a run, pass --job <job-id> or --run <run-id> instead. The positional attempt ID and the --attempt, --job, and --run flags are mutually exclusive.

For full per-sample CPU and memory readings on a single attempt, add --output json. Job and run requests return per-attempt summary stats (no per-sample samples array) even with --output json.

Flags

Examples

Show metrics for an attempt

depot ci metrics <attempt-id>

Show metrics for every attempt of a job

depot ci metrics --job <job-id>

Show metrics for every job in a run

depot ci metrics --run <run-id>

Show full per-sample metrics as JSON

depot ci metrics <attempt-id> --output json

The JSON response describes the attempt's availability, summary stats (peak and average CPU and memory utilization, sample counts, observed start and finish times), downsampling cap metadata, and the time-series samples array.

The shape of the JSON response depends on which form you use:

• --attempt (or the positional form): top-level run, workflow, and job context, plus a single attempt object with the full samples array.
• --job: top-level run, workflow, and job context, plus a flat attempts array of per-attempt summaries.
• --run: top-level run context, plus nested workflows, jobs, and attempts arrays.

For --job and --run, attempts include the same availability, summary stats, and cap metadata as --attempt, but not the samples array.

depot ci ssh

Opens an interactive terminal session to the sandbox running a CI job. Accepts a run ID or job ID. If the job hasn't started yet, the command waits for the sandbox to be provisioned.

depot ci ssh <run-id | job-id>

Flags

Examples

Connect to a job by job ID

depot ci ssh <job-id>

Connect to a specific job in a run

depot ci ssh <run-id> --job build

Print SSH connection details without connecting

depot ci ssh <run-id> --info

depot ci ssh <run-id> --info --output json

JSON response:

{
  "host": "api.depot.dev",
  "sandbox_id": "<sandbox-id>",
  "session_id": "<session-id>",
  "ssh_command": "ssh <sandbox-id>@api.depot.dev"
}

depot ci secrets

Manages secrets for your Depot CI workflows. Secrets are scoped to your Depot organization, encrypted at rest, and never readable after creation. Reference them in workflows as ${{ secrets.SECRET_NAME }}.

depot ci secrets add

depot ci secrets add SECRET_NAME

Supports three modes:

• Single secret with prompt: depot ci secrets add SECRET_NAME — omit --value and the CLI prompts you to enter the value securely (input is hidden).
• Single secret with flag: depot ci secrets add SECRET_NAME --value "val"
• Bulk KEY=VALUE pairs: depot ci secrets add FOO=bar BAZ=qux — sets multiple secrets in one command. The --value and --description flags cannot be used in this mode.

Examples

Add an org-wide secret (prompts for value):

depot ci secrets add MY_API_KEY

Add an org-wide secret with value inline:

depot ci secrets add MY_API_KEY --value "secret-value"

Add a secret with a description:

depot ci secrets add MY_API_KEY --value "secret-value" --description "API key for payment provider"

Add multiple secrets using KEY=VALUE pairs:

depot ci secrets add GITHUB_TOKEN=ghp_xxx MY_API_KEY=secret-value

Add a repo-scoped secret:

depot ci secrets add DATABASE_URL --repo owner/repo --value "postgres://..."

depot ci secrets list

depot ci secrets list

Displays names and metadata (no values) for all secrets configured for your organization. Use --repo to also show repo-specific secrets that override org-wide values.

Examples

List org-wide secrets:

depot ci secrets list

List org-wide and repo-scoped secrets together:

depot ci secrets list --repo owner/repo

depot ci secrets remove

depot ci secrets remove SECRET_NAME [SECRET_NAME...]

Alias: depot ci secrets rm. Accepts one or more secret names. Prompts for confirmation before deleting.

Examples

Remove a single secret:

depot ci secrets remove MY_API_KEY

Remove a repo-specific secret:

depot ci secrets remove MY_API_KEY --repo owner/repo

Remove multiple secrets at once:

depot ci secrets remove GITHUB_TOKEN MY_API_KEY DATABASE_URL

Remove a secret without confirmation:

depot ci secrets remove GITHUB_TOKEN MY_API_KEY --force

depot ci vars

Manages variables for your Depot CI workflows. Variables are non-secret configuration values, available in workflows as ${{ vars.VARIABLE_NAME }}. Unlike secrets, variable values can be read back through the CLI or API.

depot ci vars add

depot ci vars add VAR_NAME --value "some-value"

Supports three modes:

• Single variable with prompt: depot ci vars add VAR_NAME — omit --value and the CLI prompts you to enter the value.
• Single variable with flag: depot ci vars add VAR_NAME --value "val"
• Bulk KEY=VALUE pairs: depot ci vars add FOO=bar BAZ=qux — sets multiple variables in one command. The --value flag cannot be used in this mode.

Examples

Add an org-wide variable (prompts for value):

depot ci vars add SERVICE_NAME

Add an org-wide variable with value inline:

depot ci vars add SERVICE_NAME --value "api"

Add multiple variables using KEY=VALUE pairs:

depot ci vars add REGION=us-east-1 ENV=prod

Add a repo-scoped variable:

depot ci vars add DEPLOY_ENV --repo owner/repo --value "production"

depot ci vars list

depot ci vars list

Use --repo to also show repo-specific variables that override org-wide values.

Examples

List org-wide variables:

depot ci vars list

List org-wide and repo-scoped variables together:

depot ci vars list --repo owner/repo

depot ci vars remove

depot ci vars remove VAR_NAME [VAR_NAME...]

Alias: depot ci vars rm. Accepts one or more variable names. Prompts for confirmation before deleting.

Examples

Remove a single variable:

depot ci vars remove GITHUB_REPO

Remove a repo-specific variable:

depot ci vars remove GITHUB_REPO --repo owner/repo

Remove multiple variables at once:

depot ci vars remove GITHUB_REPO MY_SERVICE_NAME DEPLOY_ENV

Remove a variable without confirmation:

depot ci vars remove GITHUB_REPO MY_SERVICE_NAME --force