---
title: vercel ci
product: vercel
url: /docs/cli/ci
canonical_url: "https://vercel.com/docs/cli/ci"
last_updated: 2026-10-07
type: reference
prerequisites:
  - /docs/cli
related:
  - /docs/ci
  - /docs/cli/global-options
  - /docs/cli
  - /docs/cli/login
summary: Enable or disable Vercel CI for repositories, inspect runs, search logs, and rerun jobs from the command line.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# vercel ci

The `vercel ci` command lets you enable or disable repositories and inspect or rerun [Vercel CI](/docs/ci) runs. Use Vercel CLI 64.3.1 or later. Run commands from a GitHub repository with an `origin` remote, or select another remote with `--remote <NAME>` when enabling or disabling CI.


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Migrate from GitHub Actions to Vercel CI](https://vercel.com/kb/guide/github-actions-to-vercel-ci) — Move Turborepo tasks from GitHub Actions workflows to Vercel CI, migrate secrets to CI environment variables, and switch
- [Introducing Vercel CI](https://vercel.com/blog/introducing-vercel-ci)
- [vercel api](https://vercel.com/docs/cli/api) — Learn how to make authenticated HTTP requests to the Vercel API using the vercel api CLI command.
- [vercel agent-runs](https://vercel.com/docs/cli/agent-runs) — Find projects with Agent Runs, list recent runs, and inspect run metadata and conversation traces from the command line.
- [vercel list](https://vercel.com/docs/cli/list) — Learn how to list out all recent deployments for the current Vercel Project using the vercel list CLI command.
- [vercel logs](https://vercel.com/docs/cli/logs) — View and filter runtime logs or CDN request records for your Vercel project.
- [Enable or disable Vercel CI for a connected repository](https://vercel.com/docs/rest-api/vercel-ci/enable-or-disable-vercel-ci-for-a-connected-repository) — PATCH /v1/vercel-ci/repository-settings — Update Repository Settings

Full cross-link map for this page: [/docs/cli/ci.graph.md](/docs/cli/ci.graph.md)
<!-- /docsgraph:related -->

Select the team that owns the CI run, or pass [`--scope <team>`](/docs/cli/global-options#scope).

> **💡 Note:** Vercel CI is in Beta. Features and configuration may change.

## Usage

List runs, inspect the current commit, or read its failed task logs:

```bash filename="terminal"
vercel ci ls
vercel ci inspect
vercel ci logs --failed
```

*Using the \`vercel ci\` command to investigate a repository's CI runs.*

## Subcommands

### Enable a repository

`vercel ci enable` enables Vercel CI for the current Git repository. The repository must connect to a project on the selected team and must not connect to projects on other teams.

```bash filename="terminal"
vercel ci enable
vercel ci enable --remote origin --scope your-team
```

With one Git remote, the CLI selects it automatically. With multiple remotes, it prompts you to select one.

| Option | Description |
| --- | --- |
| `--remote <NAME>` | Select an existing Git remote without the picker. Required with multiple remotes in non-interactive mode. |

Running the command again for an enabled repository leaves its settings unchanged.

### Disable a repository

`vercel ci disable` disables Vercel CI for the current GitHub repository. [Update Vercel CLI](/docs/cli#updating-vercel-cli) before using this subcommand. Sign in with [`vercel login`](/docs/cli/login), or pass a [`--token`](/docs/cli/global-options#token). The repository must connect to a project on the selected team.

```bash filename="terminal"
vercel ci disable
vercel ci disable --remote upstream --scope your-team --non-interactive
```

*Disabling Vercel CI for the current repository or a specific Git remote.*

With one Git remote, the CLI selects it automatically, even if the remote isn't named `origin`. With multiple remotes, it prompts you to select one. Pass `--remote` when using JSON output or non-interactive mode with multiple remotes.

| Option | Description |
| --- | --- |
| `--remote <NAME>` | Select an existing Git remote. |
| `--json` | Write the repository settings and an `outcome` of `disabled` or `unchanged` to standard output. Also accepts `--format json`. |

Non-interactive mode returns JSON automatically. Running the command again for a disabled repository leaves its settings unchanged.

### List runs

`vercel ci ls` (also `vercel ci list`) lists runs for the current branch. Filter runs or view every branch:

```bash filename="terminal"
vercel ci ls --branch main
vercel ci ls --all-branches --status failed
vercel ci ls --format json
```

| Option | Description |
| --- | --- |
| `--branch <name>` | List runs for this branch. Defaults to the current branch. |
| `--all-branches` | List runs across every branch. Can't combine with `--branch` or `--commit`. |
| `--commit <sha>` | Filter by commit on the current branch or the branch selected with `--branch`. |
| `--status <status>` | Filter by `queued`, `running`, `succeeded`, `failed`, or `skipped`. |
| `--limit <number>` | Results per page. Defaults to 20, with a maximum of 100. |
| `--next <cursor>` | Fetch the next page using a cursor from the previous response. |

### Inspect a run

`vercel ci inspect [run]` shows a run's jobs and tasks. Find a run ID with `vercel ci ls`, or omit it to inspect the current commit:

```bash filename="terminal"
vercel ci inspect
vercel ci inspect your_run_id_here --attempt 1
vercel ci inspect --wait
```

| Option | Description |
| --- | --- |
| `--attempt <number>` | Inspect a specific attempt. Defaults to the latest attempt. |
| `--wait` | Wait up to 10 minutes for completion and exit with code `1` if the run fails. Stopping the wait doesn't cancel the run. |

### Read task logs

`vercel ci logs [run]` reads task logs for a run. Omit the run ID to use the current commit:

```bash filename="terminal"
vercel ci logs --failed
vercel ci logs --task 'web#test' --level error --level fatal
vercel ci logs --grep ECONNRESET
vercel ci logs your_run_id_here --task 'web#build' --follow
```

| Option | Description |
| --- | --- |
| `--failed` | Show only failed tasks. Can't combine with `--follow`. |
| `--task <name>` | Select a task, such as `web#test`. Repeat to select multiple tasks. |
| `--level <level>` | Filter by log level. Repeat to select multiple levels. |
| `--grep <text>` | Match text in log lines across the run, ignoring case. |
| `--attempt <number>` | Read a specific attempt. Defaults to the latest attempt. |
| `--limit <number>` | Maximum tasks to show. Defaults to 10, with a maximum of 25. |
| `--follow`, `-f` | Stream one task's logs. Requires one `--task`. JSON output uses JSON Lines. Stopping doesn't cancel the run. |

Accepted log levels are `trace`, `debug`, `command`, `info`, `warn`, `error`, `systemError`, and `fatal`.

### Search recent runs

`vercel ci grep <text>` searches task logs across recent runs. By default, it searches the last 20 runs on the current branch:

```bash filename="terminal"
vercel ci grep ECONNRESET
vercel ci grep "out of memory" --all-branches --status failed --runs 50
```

| Option | Description |
| --- | --- |
| `--branch <name>` | Search this branch. Defaults to the current branch. |
| `--all-branches` | Search every branch. Can't combine with `--branch`. |
| `--status <status>` | Filter by the latest attempt's status: `queued`, `running`, `succeeded`, `failed`, or `skipped`. |
| `--runs <number>` | Maximum recent runs to search. Defaults to 20, with a maximum of 50. The search may stop before reaching this limit. The CLI reports when results are incomplete. |
| `--level <level>` | Filter by the same log levels as `vercel ci logs`. Repeat to select multiple levels. |

### Rerun a finished run

`vercel ci rerun [run]` starts a new attempt of a finished run. Without a run ID, it selects a failed run for the current commit. To rerun a succeeded or skipped run, provide its ID:

```bash filename="terminal"
vercel ci rerun
vercel ci rerun your_run_id_here --wait
```

The `--wait` option waits up to 10 minutes and exits with code `1` if the new attempt fails. Stopping the wait doesn't cancel the run.

## Output format

Every subcommand accepts `--format json` (shorthand `-F json`) or `--json` for machine-readable output:

```bash filename="terminal"
vercel ci inspect --json
vercel ci logs your_run_id_here --task 'web#build' --follow --json
```

## Global Options

The following [global options](/docs/cli/global-options) can be passed when using the `vercel ci` command:

- [`--cwd`](/docs/cli/global-options#current-working-directory)
- [`--debug`](/docs/cli/global-options#debug)
- [`--global-config`](/docs/cli/global-options#global-config)
- [`--help`](/docs/cli/global-options#help)
- [`--local-config`](/docs/cli/global-options#local-config)
- [`--no-color`](/docs/cli/global-options#no-color)
- [`--non-interactive`](/docs/cli/global-options#non-interactive)
- [`--scope`](/docs/cli/global-options#scope)
- [`--token`](/docs/cli/global-options#token)
- [`--version`](/docs/cli/global-options#version)

For more information on global options and their usage, refer to the [options section](/docs/cli/global-options).

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.