Depot General — CLI, Auth, and Project Setup

Depot is a build acceleration platform. This skill covers CLI installation, authentication, project configuration, and organization management. For product-specific guidance, see the depot-container-builds, depot-github-runners, or depot-ci skills.

CLI Installation

bash

# macOS (Homebrew)
brew install depot/tap/depot

# Linux / CI (install script)
curl -L https://depot.dev/install-cli.sh | sh

# Specific version
curl -L https://depot.dev/install-cli.sh | sh -s 2.96.2

# Custom install directory
curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh

# Proto version manager
proto plugin add depot "https://raw.githubusercontent.com/depot/cli/refs/heads/main/proto.yaml"
proto install depot

# GitHub Actions
- uses: depot/setup-action@v1

# Container image for CI
ghcr.io/depot/cli:latest

Authentication

Token Types

Type	Scope	Created Via	Use Case
User token	All projects in all user's orgs	`depot login` or Account Settings → API Tokens	Local development
Project token	Single project	Project Settings	CI environments
Org API token	Single organization	Org Settings → API Tokens	API access, automation
OIDC trust	Single project (short-lived)	Project Settings → Trust Relationships	CI without static secrets (preferred)

Token Resolution Order

```
--token
```
flag (explicit on command)
Locally stored token (from
```
depot login
```
)
```
DEPOT_TOKEN
```
environment variable

Login

bash

depot login                           # Interactive browser login
depot login --org-id 1234567890       # Specify org
depot login --clear                   # Clear existing token first
depot logout                          # Remove saved token

OIDC Trust Relationships (Preferred for CI)

Configure in Project Settings → Trust Relationships. No static secrets — short-lived credentials.

CI Provider	Configuration
GitHub Actions	GitHub org/user name + repository name. Requires `permissions: { id-token: write }` in workflow.
CircleCI	Organization UUID + Project UUID (must use UUIDs, not friendly names)
Buildkite	Organization slug + Pipeline slug
RWX	Vault subject

GitHub Actions OIDC Example

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write    # Required for OIDC
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - uses: depot/build-push-action@v1
        with:
          project: <project-id>
          push: true
          tags: myrepo/app:latest

Token-Based CI Auth (When OIDC Not Available)

yaml

steps:
  - uses: depot/setup-action@v1
  - uses: depot/build-push-action@v1
    with:
      project: <project-id>
      token: ${{ secrets.DEPOT_TOKEN }}

Depot Registry Auth

bash

docker login registry.depot.dev -u x-token -p <any-depot-token>
# Username is always "x-token". Password is any user, project, org, or OIDC token.

# Kubernetes secret
kubectl create secret docker-registry regcred \
  --docker-server=registry.depot.dev \
  --docker-username=x-token \
  --docker-password=<depot-token>

Project Setup

bash

# Create depot.json in current directory (interactive project selection)
depot init

# Create a new project
depot projects create "my-project"
depot projects create --region eu-central-1 --cache-storage-policy 100 "my-project"
depot projects create --organization 12345678910 "my-project"

# Delete a project (org admin only)
depot projects delete --project-id <id> --yes

# List projects
depot projects list

depot.json

The only configuration file. Created by

depot init

json

{"id": "PROJECT_ID"}

Three ways to specify a project (in priority order):

```
depot.json
```
in current or parent directory
```
--project <id>
```
flag
```
DEPOT_PROJECT_ID
```
environment variable

Organization Management

bash

depot org list                    # List orgs (supports --output json/csv)
depot org switch [org-id]         # Set current org
depot org show                    # Show current org ID

Roles: User (view projects, run builds) · Owner (create/delete projects, edit settings)

Billing is per-organization. Configure usage caps, OIDC trust relationships, GitHub App connections, and cloud connections from org settings.

Environment Variables

Variable	Description
`DEPOT_TOKEN`	Auth token (user, project, or org)
`DEPOT_PROJECT_ID`	Project ID (alternative to `--project` or `depot.json` )
`DEPOT_NO_SUMMARY_LINK=1`	Suppress build links and update notices (useful in CI)
`DEPOT_INSTALL_DIR`	Custom CLI install directory
`DEPOT_DISABLE_OTEL=1`	Disable OpenTelemetry tracing

Build and Cache Management

bash

# List builds
depot list builds
depot list builds --project <id> --output json

# Reset project cache
depot cache reset .                         # Uses depot.json
depot cache reset --project <id>

# Docker integration
depot configure-docker              # Install Depot as Docker plugin + default builder
depot configure-docker --uninstall  # Remove

GitHub Actions — Depot Actions Reference

Action	Purpose
`depot/setup-action@v1`	Install `depot` CLI
`depot/build-push-action@v1`	Drop-in for `docker/build-push-action` (same inputs/outputs)
`depot/bake-action@v1`	Drop-in for `docker/bake-action`
`depot/use-action@v1`	Set Depot as default Docker Buildx builder
`depot/pull-action`	Pull from Depot Registry

API Access

Protocol: Connect framework (gRPC + HTTP JSON). SDKs:

@depot/sdk-node

(Node.js),

depot/depot-go

(Go).

javascript

import {depot} from '@depot/sdk-node'
const headers = { Authorization: `Bearer ${process.env.DEPOT_TOKEN}` }

// List projects
const result = await depot.core.v1.ProjectService.listProjects({}, {headers})

// Create a build
const build = await depot.build.v1.BuildService.createBuild(
  {projectId: '<id>'}, {headers}
)

Pricing Plans

Plan	Cost	Build Minutes	Cache	Runners
Developer	$20/mo	2,000/mo	25 GB	Linux, Windows
Startup	$200/mo	20,000/mo + $0.004/min	250 GB	Linux, Windows, macOS
Business	Custom	Custom	Custom	All + GPU

Per-second billing, no minimums. Additional cache: $0.20/GB/month.

depot-general

NPX Install

Tags

SKILL.md Content

Depot General — CLI, Auth, and Project Setup

CLI Installation

Authentication

Token Types

Token Resolution Order

Login

OIDC Trust Relationships (Preferred for CI)

GitHub Actions OIDC Example

Token-Based CI Auth (When OIDC Not Available)

Depot Registry Auth

Project Setup

depot.json

Organization Management

Environment Variables

Build and Cache Management

GitHub Actions — Depot Actions Reference

API Access

Pricing Plans