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 the command 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.

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

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

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

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 (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

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

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.

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

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.

depot ci vars list

depot ci vars list

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

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