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. The two flags are mutually exclusive: pass one or the other, not both.

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 run show

Shows a single CI run's identity, repo, ref, SHAs, trigger, status, and timing fields.

depot ci run show <run-id>

Alias: depot ci run get.

For the run's nested workflow, job, and attempt status, use depot ci status.

Flags

Examples

Show a run:

depot ci run show <run-id>

Show a run as JSON:

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

JSON response:

{
  "org_id": "<org-id>",
  "run_id": "<run-id>",
  "repo": "depot/api",
  "ref": "refs/heads/main",
  "sha": "<merge-sha>",
  "head_sha": "<head-sha>",
  "trigger": "push",
  "status": "finished",
  "created_at": "2026-04-30T14:01:00Z",
  "started_at": "2026-04-30T14:02:00Z",
  "finished_at": "2026-04-30T14:25:15Z"
}

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 run, an entire workflow (all its jobs), or a single job within a workflow.

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

With no scope flags, the entire run is cancelled. Pass --workflow to cancel one workflow and all its jobs, or --job to cancel a single job. The --workflow and --job flags 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 run (all workflows and jobs within it)

depot ci cancel <run-id>

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

JSON response:

{"run_id": "<run-id>", "status": "cancelled"}

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 summary

Fetches the authored step summary markdown for a CI job attempt, or for the current or latest attempt of a job.

depot ci summary <attempt-id | job-id>

When given a job ID, the command resolves to the latest attempt automatically and prints a Using attempt #N <attempt-id> for job <job-id>. line to stderr (text mode only) before the markdown.

If no summary was authored for the resolved attempt, the command prints a short explanation to stdout and exits successfully. The same applies when a job has no attempts yet.

Flags

Examples

Fetch a summary for an attempt

depot ci summary <attempt-id>

Fetch the current or latest attempt's summary for a job

depot ci summary <job-id>

Output the summary as JSON

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

JSON response:

{
  "org_id": "<org-id>",
  "run_id": "<run-id>",
  "workflow_id": "<workflow-id>",
  "job_id": "<job-id>",
  "attempt_id": "<attempt-id>",
  "attempt": 1,
  "job_status": "finished",
  "attempt_status": "finished",
  "has_summary": true,
  "empty_reason": "",
  "step_count": 3,
  "markdown": "## Build\n\nok\n"
}

When the attempt did not produce a summary, has_summary is false and empty_reason is set (for example, no_summary or no_attempt).

depot ci artifacts

Lists CI artifact metadata and downloads one artifact by ID. Download URLs are never returned by list; use artifacts download to fetch the file.

depot ci artifacts list

depot ci artifacts list <run-id>

Lists artifacts produced by a CI run. Use --workflow, --job, or --attempt to narrow the result to one workflow, job, or attempt within the run.

Flags

Examples

List every artifact for a run:

depot ci artifacts list <run-id>

List artifacts for one job as JSON:

depot ci artifacts list <run-id> --job <job-id> --output json

The JSON response is {"artifacts": [...]} where each artifact includes artifact_id, run_id, workflow_id, workflow_path, job_id, job_key, attempt_id, attempt, name, size_bytes, and created_at.

depot ci artifacts download

depot ci artifacts download <artifact-id>

Downloads one CI artifact by its artifact ID. If --output-file is omitted, the file is written to the artifact's original name in the current directory; control characters and path separators in the name are sanitized to _. The command refuses to overwrite an existing file.

Flags

Examples

Download an artifact to its default filename:

depot ci artifacts download <artifact-id>

Download an artifact to a specific file:

depot ci artifacts download <artifact-id> --output-file coverage.zip

depot ci diagnose

Diagnoses a failed Depot CI run, workflow, job, or attempt using bounded stored failure context. The command groups similar failures across attempts and, where available, surfaces a diagnosis and a possible fix for each group, together with evidence lines and drill-down commands for the next step.

depot ci diagnose --run <run-id>
depot ci diagnose --workflow <workflow-id>
depot ci diagnose --job <job-id>
depot ci diagnose --attempt <attempt-id>

Exactly one of --run, --workflow, --job, or --attempt is required. Positional target IDs aren't accepted.

The text output adapts to the diagnosis state:

• Grouped: lists each failure group with the failure count, diagnosis, possible fix, and a small set of representative attempts and evidence lines.
• Focused: a single representative attempt with its error, diagnosis, possible fix, and relevant log lines.
• Empty: prints "No CI failures found for this target." with an optional reason.
• Over limit: the target spans more failed candidates than the diagnosis bounds allow. The output includes a "Narrower targets" breakdown with ready-to-run drill-down commands.

Flags

Examples

Diagnose a run

depot ci diagnose --run <run-id>

Diagnose a single attempt

depot ci diagnose --attempt <attempt-id>

Diagnose a job as JSON

depot ci diagnose --job <job-id> --output json

The JSON response includes state (empty, grouped_failures, focused_failure, or over_limit), target, context (run, repo, ref, SHA, workflow, job, and attempt identifiers with their statuses), bounds (diagnosis caps and omitted counts), failure_groups (with diagnosis, possible_fix, and representative attempts), representative_attempts, next_commands (drill-down command suggestions), and over_limit_breakdown when the result is over limit.

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": "exec.depot.dev",
  "sandbox_id": "<sandbox-id>",
  "session_id": "<session-id>",
  "ssh_command": "ssh <sandbox-id>@exec.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 }}.

Each secret name groups one or more variants. A variant holds a value and an optional set of availability selectors (--repo, --env, --branch, --workflow) that match jobs by repository, GitHub environment, branch, and workflow file. A variant with no selectors applies to every job in the organization. For how Depot resolves matching variants at run time, see Manage secrets and variables.

depot ci secrets add

depot ci secrets add <secret-name> [variant]
depot ci secrets add KEY=VALUE [KEY=VALUE...]

Adds a secret variant. Supports three modes:

• Interactive prompt: depot ci secrets add SECRET_NAME prompts you to enter the value securely (input is hidden).
• Piped stdin: printf '%s' "$VALUE" | depot ci secrets add SECRET_NAME reads the value from stdin.
• Bulk KEY=VALUE pairs: depot ci secrets add FOO=bar BAZ=qux sets multiple secrets in one command. The --description flag isn't allowed in this mode.

Pass an optional second positional argument to name the variant (for example, production). Without a variant name, the command writes to the default variant for that secret. Use --repo, --env, --branch, and --workflow to limit when the variant applies; repeat any flag to match multiple values. Without selectors, the variant applies to every job in the organization.

Flags

Examples

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

depot ci secrets add MY_API_KEY

Add a secret from piped stdin:

printf '%s' "$MY_API_KEY" | depot ci secrets add MY_API_KEY

Add a variant limited to a repo, branch, and environment:

printf '%s' "$DEPLOY_KEY" | depot ci secrets add DEPLOY_KEY production \
  --repo owner/repo --branch main --env production

Add multiple secrets using KEY=VALUE pairs:

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

depot ci secrets set

depot ci secrets set <secret-name> [variant]

Creates or updates a single secret variant. Unlike add, this command never accepts KEY=VALUE pairs and is the recommended form for scripts that pipe values: pass --from-stdin together with piped input, otherwise the command runs interactively.

Pass an optional second positional argument to name the variant. Without a variant name, the command writes the default variant. Use --repo, --env, --branch, and --workflow to limit when the variant applies; repeat any flag to match multiple values.

Flags

Examples

Set the default variant (prompts for value):

depot ci secrets set MY_API_KEY

Set a named variant from piped stdin:

printf '%s' "$MY_API_KEY" | depot ci secrets set MY_API_KEY production --from-stdin

Set a variant scoped to multiple branches:

printf '%s' "$MY_API_KEY" | depot ci secrets set MY_API_KEY release --from-stdin \
  --repo owner/repo --branch main --branch 'release/*'

depot ci secrets bulk

depot ci secrets bulk [variant] --file <path>
depot ci secrets bulk [variant] --from-stdin

Imports CI secrets from a dotenv file or piped stdin. Input is parsed as KEY=VALUE entries; blank lines and # comments are ignored. The same variant name and availability selectors apply to every secret in the input.

Exactly one of --file or --from-stdin is required.

Flags

Examples

Import a .env file scoped to a repository:

depot ci secrets bulk --file .env --repo owner/repo

Pipe a .env file from stdin:

cat .env | depot ci secrets bulk --from-stdin --repo owner/repo

Import every entry as a named variant on release branches:

depot ci secrets bulk production --file .env \
  --repo owner/repo --branch main --branch 'release/*'

depot ci secrets get

depot ci secrets get <secret-name> [variant]
depot ci secrets get --variant-id <id>

Shows one secret variant with full, untruncated attributes. Use selectors to disambiguate when a secret has multiple variants that could match.

The command errors if zero or more than one variant matches. If multiple match, narrow the result with --variant-id, the optional variant positional, or additional --repo, --env, --branch, or --workflow flags.

Flags

Examples

Show a variant by secret and variant name:

depot ci secrets get MY_API_KEY production

Disambiguate with selectors:

depot ci secrets get MY_API_KEY production --repo owner/repo --branch main

Fetch by variant ID:

depot ci secrets get --variant-id <variant-id>

Output as JSON:

depot ci secrets get MY_API_KEY production --output json

depot ci secrets list

depot ci secrets list [<secret-name>]

Lists CI secrets and their variants for your organization. Secret values are never returned. Pass a secret name to scope the output to that secret and its variants.

Alias: depot ci secrets ls.

Use --repo, --env, --branch, and --workflow to filter the variant rows by their attributes; repeat any flag to widen the match. With no filters, every variant is shown.

Flags

Examples

List every secret and its variants:

depot ci secrets list

List variants filtered to a repo and branch:

depot ci secrets list --repo owner/repo --branch main

List one secret with all its variants:

depot ci secrets list MY_API_KEY

Output as JSON:

depot ci secrets list --output json

depot ci secrets remove

depot ci secrets remove <secret-name> [<secret-name>...]

Removes one or more CI secrets. Prompts for confirmation before deleting unless --force is set.

Alias: depot ci secrets rm.

By default, each positional argument is treated as a secret name and the command removes the entire secret with every variant under it. To remove a single variant, pass --variant <name> or use selectors (--repo, --env, --branch, --workflow) that uniquely identify one variant. --all makes whole-secret removal explicit and cannot be combined with selectors or --variant.

Flags

Examples

Remove a secret and every variant:

depot ci secrets remove MY_API_KEY

Remove a named variant:

depot ci secrets remove MY_API_KEY --variant production

Remove a variant by selectors:

depot ci secrets remove DEPLOY_KEY --repo owner/repo --branch main

Remove multiple secrets without the confirmation prompt:

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.

Like secrets, each variable name groups one or more variants, each with optional --repo, --env, --branch, and --workflow selectors. A variant with no selectors applies to every job in the organization. For how Depot resolves matching variants at run time, see Manage secrets and variables.

depot ci vars add

depot ci vars add <variable-name> [variant]
depot ci vars add KEY=VALUE [KEY=VALUE...]

Adds a variable variant. Supports three modes:

• Interactive prompt: depot ci vars add VAR_NAME prompts you to enter the value.
• Flag value: 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 isn't allowed in this mode.

Pass an optional second positional argument to name the variant. Without a variant name, the command writes the default variant. Use --repo, --env, --branch, and --workflow to limit when the variant applies; repeat any flag to match multiple values.

Flags

Examples

Add an org-wide variable with a flag value:

depot ci vars add SERVICE_NAME --value "api"

Add a named variant scoped to a repo:

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

Add a variant limited to a branch and environment:

depot ci vars add DEPLOY_ENV production --repo owner/repo \
  --branch main --env production --value "production"

Add multiple variables using KEY=VALUE pairs:

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

depot ci vars set

depot ci vars set <variable-name> [variant]

Creates or updates a single variable variant. Unlike add, this command never accepts KEY=VALUE pairs and exposes --description for tagging the variant.

Pass an optional second positional argument to name the variant. Without a variant name, the command writes the default variant. Use --repo, --env, --branch, and --workflow to limit when the variant applies; repeat any flag to match multiple values.

Flags

Examples

Set the default variant:

depot ci vars set DEPLOY_ENV --value "staging"

Set a named variant with a description:

depot ci vars set DEPLOY_ENV production --value "production" \
  --description "Production deploy environment"

Set a variant scoped to multiple branches:

depot ci vars set DEPLOY_ENV release --value "release" \
  --repo owner/repo --branch main --branch 'release/*'

depot ci vars list

depot ci vars list [<variable-name>]

Lists CI variables and their variants for your organization, including the variant values. Pass a variable name to scope the output to that variable and its variants.

Alias: depot ci vars ls.

Use --repo, --env, --branch, and --workflow to filter the variant rows by their attributes; repeat any flag to widen the match. With no filters, every variant is shown.

Flags

Examples

List every variable and its variants:

depot ci vars list

List variants filtered to a repo and branch:

depot ci vars list --repo owner/repo --branch main

List one variable with all its variants:

depot ci vars list DEPLOY_ENV

Output as JSON:

depot ci vars list --output json

depot ci vars remove

depot ci vars remove <variable-name> [<variable-name>...]

Removes one or more CI variables. Prompts for confirmation before deleting unless --force is set.

Alias: depot ci vars rm.

By default, each positional argument is treated as a variable name and the command removes the entire variable with every variant under it. To remove a single variant, pass --variant <name> or use selectors (--repo, --env, --branch, --workflow) that uniquely identify one variant. --all makes whole-variable removal explicit and cannot be combined with selectors or --variant.

Flags

Examples

Remove a variable and every variant:

depot ci vars remove DEPLOY_ENV

Remove a named variant:

depot ci vars remove DEPLOY_ENV --variant production

Remove a variant by selectors:

depot ci vars remove DEPLOY_ENV --repo owner/repo --branch main

Remove multiple variables without the confirmation prompt:

depot ci vars remove DEPLOY_ENV SERVICE_NAME --force