Depot CLI: Depot CI commands reference

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

Other Depot product CLI references:

`depot ci migrate`

Automates migrating GitHub Actions workflows to Depot CI. Launches an interactive wizard that discovers workflows in .github/workflows/, analyzes them for compatibility, copies selected workflows to .depot/workflows/, and prompts you to configure any referenced secrets and variables.

depot ci migrate

What the command does

Discovers all workflow files in .github/workflows/.
Analyzes each workflow for compatibility with Depot CI.
Prompts you to select which workflows to migrate.
Creates a .depot/ directory and copies selected workflows (and any local actions from .github/actions/) there.
Detects secrets and variables referenced in the selected workflows and prompts you to enter their values.

What gets copied

Source	Destination
`.github/workflows/<selected>.yml`	`.depot/workflows/<selected>.yml`
`.github/actions/`	`.depot/actions/`

Flags

Flag	Description
`--yes`	Run in non-interactive mode, migrating all discovered workflows automatically
`--secret KEY=VALUE`	Pre-supply a secret value; can be repeated for multiple secrets
`--var KEY=VALUE`	Pre-supply a variable value; can be repeated for multiple variables
`--repo <owner/repo>`	Scope secrets and variables to a specific repository; auto-detected from git remote if not provided
`--overwrite`	Overwrite an existing `.depot/` directory without prompting
`--org <id>`	Specify a Depot organization ID (required if you belong to more than one organization)
`--token <token>`	Depot API token

Non-interactive mode

Use --yes to run the migration without any prompts. Combine it with --secret and --var to supply values upfront:

depot ci migrate --yes \
  --secret NPM_TOKEN=npm_abc123 \
  --secret DATABASE_URL=postgres://... \
  --var SERVICE_NAME=api \
  --org my-org-id

If a workflow references a secret or variable that you haven't supplied via flags, the migration completes with a warning. Add missing values later with depot ci secrets add or depot ci vars add.

Compatibility analysis

Before copying any files, the wizard analyzes each workflow and shows a summary of issues:

No issues: The workflow is fully compatible and safe to migrate.
Warnings: Features are partially supported. The workflow will run but behavior may differ from GitHub Actions.
Critical issues: Features are unsupported. The workflow is unlikely to run correctly in Depot CI today.

For the full compatibility matrix, see Compatibility with GitHub Actions.

`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 uncommitted changes relative to the default branch, the CLI automatically detects them, uploads a patch to Depot Cache, and injects a patch-application step after actions/checkout in each selected job.

Flags

Flag	Description
`--workflow <path>`	Path to the workflow YAML file (required)
`--job <name>`	Job name to run; can be repeated to select multiple jobs. Omit to run all jobs.
`--ssh`	Start the run and connect to the job's sandbox via interactive terminal. Requires exactly one `--job`.
`--ssh-after-step <n>`	Insert an SSH debug session (via tmate) after the nth step (1-based). Requires exactly one `--job`.
`--org <id>`	Organization ID (required when user is a member of multiple organizations)
`--token <token>`	Depot API token

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.

`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

Flag	Description
`--status <status>`	Filter by status; can be repeated. Values: `queued`, `running`, `finished`, `failed`, `cancelled`
`-n <number>`	Number of runs to return (default: `50`)
`--output json`	Output as JSON instead of a table
`--org <id>`	Organization ID (required when user is a member of multiple organizations)
`--token <token>`	Depot API token

Examples

# List failed runs
depot ci run list --status failed

# 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

`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.

Flags

Flag	Description
`--org <id>`	Organization ID (required when user is a member of multiple organizations)
`--token <token>`	Depot API token

`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

Flag	Description
`--job <key>`	Job key to select (required when the run has multiple jobs)
`--workflow <path>`	Workflow path to filter jobs (for example, `ci.yml`)
`--org <id>`	Organization ID (required when user is a member of multiple organizations)
`--token <token>`	Depot API token

Examples

# Fetch logs by attempt ID
depot ci logs <attempt-id>

# Fetch logs for the latest attempt of a run (single-job workflow)
depot ci logs <run-id>

# Fetch logs for a specific job in a run
depot ci logs <run-id> --job test

# Disambiguate with workflow path when job names overlap across workflows
depot ci logs <run-id> --job build --workflow ci.yml

`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

Flag	Description
`--job <key>`	Job key to connect to (required when the run has multiple jobs)
`--info`	Print SSH connection details instead of connecting interactively
`--output json`	Output SSH connection details as JSON (use with `--info`)
`--org <id>`	Organization ID (required when user is a member of multiple organizations)
`--token <token>`	Depot API token

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

# Print SSH connection details as JSON
depot ci ssh <run-id> --info --output json

`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

If you omit --value, the CLI prompts you to enter the value securely (input is hidden).

Flag	Description
`--value <value>`	Secret value
`--description <text>`	Human-readable description of the secret
`--repo <owner/repo>`	Scope the secret to a specific repository; without this flag, the secret is org-wide
`--org <id>`	Organization ID
`--token <token>`	Depot API token

`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.

Flag	Description
`--repo <owner/repo>`	Also show repo-specific secrets for this repository
`--output json`	Output as JSON instead of a table
`--org <id>`	Organization ID
`--token <token>`	Depot API token

`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.

# 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 without confirmation
depot ci secrets remove GITHUB_TOKEN MY_API_KEY --force

Flag	Description
`--repo <owner/repo>`	Remove a repo-specific secret instead of the org-wide secret
`--force`	Skip confirmation prompt
`--org <id>`	Organization ID
`--token <token>`	Depot API token

`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"

If you omit --value, the CLI prompts you to enter the value.

Flag	Description
`--value <value>`	Variable value
`--repo <owner/repo>`	Scope the variable to a specific repository; without this flag, the variable is org-wide
`--org <id>`	Organization ID
`--token <token>`	Depot API token

`depot ci vars list`

depot ci vars list

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

Flag	Description
`--repo <owner/repo>`	Also show repo-specific variables for this repository
`--output json`	Output as JSON instead of a table
`--org <id>`	Organization ID
`--token <token>`	Depot API token

`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.

# 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 without confirmation
depot ci vars remove GITHUB_REPO MY_SERVICE_NAME --force

Flag	Description
`--repo <owner/repo>`	Remove a repo-specific variable instead of the org-wide variable
`--force`	Skip confirmation prompt
`--org <id>`	Organization ID
`--token <token>`	Depot API token