depot · depot-bot · May 7, 2026
diff --git a/content/ci/how-to-guides/custom-images.mdx b/content/ci/how-to-guides/custom-images.mdx
@@ -10,7 +10,7 @@ Build a reusable custom image from the Depot base image that includes your tools
 
 ## How it works
 
-You build a custom image in Depot CI using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely.
+A custom image in Depot CI is a snapshot of a sandbox environment. You build the custom image using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely.
 
 <NoteCallout fullWidth>
   The snapshot action can only be used in workflows running on Depot CI. It's not compatible with GitHub Actions or
@@ -19,7 +19,7 @@ You build a custom image in Depot CI using a job that runs only your setup steps
 
 ## Snapshot a sandbox to build a custom image
 
-Create a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. This is a separate workflow that only creates your custom image and pushes it to the Depot Registry. You'll need to run this workflow initially to create the image and then only when dependencies change.
+Build a custom image using a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. The job creates your custom image and pushes it to the Depot Registry. Use a separate workflow for the build image job, and then use the resulting image in one or more other workflows. This pattern is usually the most efficient because you run the image build workflow once to create the image and then only when dependencies change. If your use case differs, you can also run the build image job in the same workflow as other jobs that subsequently use it.
 
 <NoteCallout fullWidth>
   Actions that set or change environment variables (such as actions/setup-node) need to be in both the build image
@@ -63,7 +63,9 @@ Any job in any workflow on Depot CI can specify your custom image. The custom im
 To run a job on a custom image, specify `runs-on` with `size` and `image` keys (both required).
 
 - `size`: the size of the sandbox
-- `image`: is the Depot registry URL you specified in the build image workflow
+- `image`: the Depot registry URL of the image (defined in the build image workflow)
+
+The `runs-on.image` value must be a Depot registry URL for an image created using the `depot/snapshot-action` as described in [Snapshot a sandbox to build a custom image](#snapshot-a-sandbox-to-build-a-custom-image). You can't use any other images or artifacts, even if they exist in the Depot registry.
 
 Example specifying a custom image in a job:
 

diff --git a/content/cli/reference/depot-ci.mdx b/content/cli/reference/depot-ci.mdx
@@ -391,7 +391,7 @@ 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 latest attempt's ID, status, sandbox ID, session ID, and a ready-to-run `depot ci logs` command are shown. If the job has more than one attempt, all attempts are listed.
+- 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:
 
@@ -498,15 +498,65 @@ Replace `<run-id>` with the run ID returned by `depot ci run` or visible in the
 - 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.
+- 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
 
 | Flag              | Description                                                                |
 | ----------------- | -------------------------------------------------------------------------- |
+| `--output json`   | Output as JSON instead of the hierarchical text view                       |
 | `--org <id>`      | Organization ID (required when user is a member of multiple organizations) |
 | `--token <token>` | Depot API token                                                            |
 
+### Examples
+
+#### Show the status as JSON
+
+```bash
+depot ci status <run-id> --output json
+```
+
+JSON response:
+
+```json
+{
+  "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`
@@ -712,12 +762,16 @@ 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                                                            |
+| 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`)                       |
+| `--follow`, `-f`       | Follow live logs as they're produced                                       |
+| `--timestamps`         | Prefix plain log lines with UTC timestamps                                 |
+| `--output <format>`    | Output format: `text` (default) or `json` (newline-delimited events)       |
+| `--output-file <path>` | Write a finite log export to the given file path                           |
+| `--org <id>`           | Organization ID (required when user is a member of multiple organizations) |
+| `--token <token>`      | Depot API token                                                            |
 
 ### Examples
 
@@ -745,6 +799,112 @@ depot ci logs <run-id> --job test
 depot ci logs <run-id> --job build --workflow ci.yml
 ```
 
+#### Follow live logs
+
+```bash
+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
+
+```bash
+depot ci logs <attempt-id> --timestamps
+```
+
+#### Emit logs as newline-delimited JSON events
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+depot ci logs <attempt-id> --output-file logs.txt
+```
+
+Use `--output-file` together with `--output json` to download a JSONL export:
+
+```bash
+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.
+
+```bash
+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
+
+| Flag                     | Description                                                                |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `--attempt <attempt-id>` | Job attempt ID (alias for the positional argument)                         |
+| `--job <job-id>`         | Show metrics for every attempt of the given job                            |
+| `--run <run-id>`         | Show metrics for every job and attempt in the given run                    |
+| `--output <format>`      | Output format: `text` (default) or `json`                                  |
+| `--org <id>`             | Organization ID (required when user is a member of multiple organizations) |
+| `--token <token>`        | Depot API token                                                            |
+
+### Examples
+
+#### Show metrics for an attempt
+
+```bash
+depot ci metrics <attempt-id>
+```
+
+#### Show metrics for every attempt of a job
+
+```bash
+depot ci metrics --job <job-id>
+```
+
+#### Show metrics for every job in a run
+
+```bash
+depot ci metrics --run <run-id>
+```
+
+#### Show full per-sample metrics as JSON
+
+```bash
+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`

diff --git a/content/container-builds/how-to-guides/continuous-integration.mdx b/content/container-builds/how-to-guides/continuous-integration.mdx
@@ -20,6 +20,7 @@ Running `depot` in a continuous integration environment is a great way to get fa
 - [Bitbucket Pipelines](/docs/container-builds/integrations/bitbucket-pipelines)
 - [Buildkite](/docs/container-builds/integrations/buildkite)
 - [CircleCI](/docs/container-builds/integrations/circleci)
+- [Depot CI](/docs/container-builds/integrations/depot-ci)
 - [GitHub Actions](/docs/container-builds/integrations/github-actions)
 - [GitLab CI](/docs/container-builds/integrations/gitlab-ci)
 - [Google Cloud Build](/docs/container-builds/integrations/google-cloud-build)