---
title: Workflow & CLI
description: Run single actions from GitHub Actions workflows and from the Copilot CLI.
---

# Workflow & CLI

You can run single actions in two ways: from a **GitHub Actions workflow** (for example, a scheduled job or manual trigger) or from the **`copilot` CLI** locally.

## Recommended: initialize with the CLI

For a new repository, install the published package globally with `pnpm` and let
`copilot setup` initialize the repository. This is the supported onboarding path:

```bash
pnpm add --global @vypdev/copilot
copilot --version
cd /path/to/your/repository
copilot setup
```

The wizard copies the selected workflows and templates, creates the required
labels and issue types, and configures the Variables and Secrets required by the
selected features. Use `copilot setup --dry-run` to review the plan first. See
[How to use](/how-to-use) for the setup PAT, workflow PAT, and scope details.

## Manual: run the Action from a GitHub Actions workflow

Add a job that sets `single-action` and any required inputs (`single-action-issue`, `single-action-version`, etc.):

```yaml
jobs:
  run-check-progress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          persist-credentials: false
      - uses: vypdev/copilot@v3
        with:
          token: ${{ secrets.PAT }}
          single-action: check_progress_action
          single-action-issue: '123'
```

Use `workflow_dispatch` to run on demand, or trigger the workflow from another event. See [Single Actions Configuration](/single-actions/configuration) for the workflow inputs.

## Install or update the CLI

The published package is `@vypdev/copilot` and exposes one global executable:
**`copilot`**. Install it with pnpm, then run repository-dependent commands from
the target repository.

### Install the published package

```bash
pnpm add --global @vypdev/copilot
copilot --version
```

The package requires Node.js 24 or newer. The npm scope does not change the
executable name: the command remains `copilot`.

### Install from a checkout

Use a repository checkout when testing unreleased changes or developing Copilot:

```bash
git clone https://github.com/vypdev/copilot.git
cd copilot
corepack pnpm install . --global
```

The repository includes the generated `build/` directory. If you are installing from a checkout where `build/` is missing, build it first:

```bash
corepack pnpm install
corepack pnpm run build
corepack pnpm install . --global --force
```

### Update the global pnpm installation

Update to the latest published version with:

```bash
copilot upgrade
copilot --version
```

Run `copilot upgrade` from any directory. It updates the published pnpm
installation and does not require a target repository or GitHub token. If the
installed version does not include this command, run
`pnpm add --global @vypdev/copilot@latest` once. You can also update it directly
with `pnpm update --global @vypdev/copilot`.

Normal Copilot CLI commands also perform a lightweight update check against npm. It is informational only: the result is cached locally for 24 hours, the network request has a short timeout, and failures are ignored so the command continues normally. When a newer release is found, the CLI prints `A new version (x.y.z) is available. Run "copilot upgrade".` The check is skipped for `copilot upgrade`, `--version`, and help. Set `COPILOT_DISABLE_UPDATE_CHECK=1` to opt out.

Verify the installed package and executable:

```bash
command -v copilot
copilot --version
pnpm list --global --depth 0 @vypdev/copilot
```

### Reinstall or update from a checkout

Pull the version you want into the Copilot checkout, then reinstall the local package globally:

```bash
cd /path/to/copilot
git pull --ff-only origin master
corepack pnpm install . --global --force
```

Verify that the executable is on `PATH` and that the installed package is the expected one:

```bash
command -v copilot
copilot --help
copilot --version
corepack pnpm list --global --depth 0 @vypdev/copilot
```

If the command is not found after installation, configure pnpm's global bin
directory in your shell's `PATH` and open a new shell.

Run `pnpm bin --global` or consult `pnpm setup` to locate the global executable
directory when configuring `PATH`.

## Local CLI prerequisites

Run repository-dependent commands from the **root of the target repository**, not necessarily from the Copilot checkout. `copilot upgrade`, `copilot --version`, and help can run from any directory. The target repository must:

- be a Git worktree;
- have an `origin` remote pointing to a GitHub repository;
- have `PERSONAL_ACCESS_TOKEN` available through the environment, or pass `--token` to commands that support it;
- have the selected agent runtime and credentials configured for AI commands.

For local use, prefer the hidden prompt or an environment variable instead of putting a token in shell history. `copilot setup` and `copilot doctor` prompt for the setup PAT; other commands accept `-t, --token` or `PERSONAL_ACCESS_TOKEN`. `copilot do` does not use a GitHub PAT option and reads the configured agent environment instead. See [Authentication](/authentication) and [Agent CLI configuration](/agents/cli-configuration).

## Command reference

All commands support `-h, --help`. The `-d, --debug` option enables additional diagnostics where listed below.

### `copilot setup`

Initializes the current GitHub repository through an interactive English-language wizard. It can select the workflows and templates to install, route each Copilot task to Codex, OpenCode, or Cursor, configure repository behavior and AI policy, inspect and provision GitHub Actions Variables and Secrets at repository or organization scope, verify access, and create the configured labels and issue types. If the repository has no version tags, setup asks whether it should create `v1.0.0`.

| Option | Required | Description |
| --- | --- | --- |
| `-t, --token <token>` | No | Setup PAT override. Otherwise uses the hidden prompt interactively or `PERSONAL_ACCESS_TOKEN` from the environment. |
| `-d, --debug` | No | Enables debug logging. |
| `--agent <provider>` | No | Preselect one runtime for every task: `codex`, `opencode`, or `cursor`. |
| `--features <features>` | No | Preselect a comma-separated feature list, or `all`. Feature names are listed below. |
| `--config <path>` | No | Load non-secret YAML/JSON setup overrides. Interactive answers can still refine them. |
| `--non-interactive` | No | Use defaults, flags, config-file values, and explicit credentials without creating a terminal or prompting. |
| `--yes` | No | Approve only the final plan; it does not fill missing configuration or credentials. |
| `--dry-run` | No | Print the complete plan without changing files or GitHub. A token is not required. |
| `--skip-variables` | No | Copy files and provision metadata without changing Repository Variables. |
| `--skip-secrets` | No | Do not validate or create/update repository Secrets. |
| `--variables-scope <scope>` | No | Default scope for Variables: `repository` or `organization`. |
| `--secrets-scope <scope>` | No | Default scope for Secrets: `repository` or `organization`. |
| `--variables-visibility <visibility>` | No | Organization Variable visibility: `selected`, `private`, or `all`. |
| `--secrets-visibility <visibility>` | No | Organization Secret visibility: `selected`, `private`, or `all`. |
| `--variable-scope <name=scope>` | No | Repeat to mix repository and organization scopes per Variable. |
| `--secret-scope <name=scope>` | No | Repeat to mix repository and organization scopes per Secret. |
| `--update-workflows` | No | Approve updates to changed setup workflows already present in the repository. |
| `--workflow-pat <token>` | No | Workflow PAT for non-interactive setup; prefer the hidden prompt. |
| `--secret <name=value>` | No | Repeat for provider credentials in non-interactive setup; values can appear in shell history. |

```bash
copilot setup
```

Run it from the target repository root. Existing setup files are not overwritten unless you approve the update prompt or pass `--update-workflows`. The interactive flow installs the selected workflows/templates, asks for agent routing and operational settings, inspects the repository's effective Actions resources, and asks separately where Secrets and Variables should live. Organization scope requires an organization-owned repository and the corresponding organization permissions on the setup PAT. Existing repository resources take precedence over organization resources; setup preserves an inherited organization resource unless you explicitly request a repository override.

The questionnaire is forward-only and immutable. Its stable stages are capabilities, agent runtime, model defaults, optional role overrides, repository, deployment, Bugbot, optional Projects, provisioning, storage, review, and confirmation. `Ctrl-C` or end-of-input closes the prompt once, exits 130, and writes nothing. Declining the final plan exits 0 and also writes nothing; rerun setup or edit the config file to change earlier answers.

The wizard covers these features: `issues`, `pullRequests`, `commits`, `issueComments`, `pullRequestComments`, `release`, `hotfix`, `agentProvisioning`, `credentialHealth`, `inactiveIssueClosure`, `issueTemplates`, and `pullRequestTemplate`. The agent tasks are `planner`, `findings`, `reviewer`, `fixer`, and `tester`; each can use any of the three supported runtimes independently. Model provider, model, effort, branch strategy, locales, AI ignore patterns, project columns, Bugbot policy, provisioning mode, and initial-tag creation are also configurable. Cursor is available as an experimental runtime and is called out in the review plan with its extra credential/checksum requirements.

For automation, use the same defaults without prompts:

```bash
copilot setup --non-interactive --yes
copilot setup --dry-run
copilot setup --non-interactive --yes --features issues,pullRequests,commits,issueComments,pullRequestComments --agent codex
```

For unattended credential provisioning, keep the setup PAT in a protected CI secret and pass credential values explicitly (never commit them):

```bash
copilot setup --non-interactive --yes --update-workflows \
  --token "$SETUP_PAT" \
  --workflow-pat "$WORKFLOW_PAT" \
  --secret "OPENAI_API_KEY=$OPENAI_API_KEY" \
  --secrets-scope organization \
  --secrets-visibility selected \
  --variables-scope repository \
  --variable-scope AGENT_PROVIDER=repository
```

The explicit `--workflow-pat` and `--secret` options are provided for automation and can appear in process listings or shell history. The interactive hidden prompt is safer for a human operator.

### `copilot doctor`

Checks the setup PAT, selected workflow templates, Repository Variables, Secret presence, remote credential health, and live merge-queue readiness for production and development targets. It combines classic branch protection with effective rulesets and emits stable, ordered checks with `pass`, `warn`, `fail`, or dependency-blocked `skipped` status. Active release branches are discovered and revalidated at hotfix runtime. A failed setup PAT does not hide independent local drift: local checks continue and remote dependants name the blocking check. Independent remote probes use a fixed maximum concurrency of four, but their completion order never changes report order. Doctor exits non-zero exactly when at least one check fails.

Doctor's composition contains query ports only: it never creates, updates, deletes, or overwrites repository configuration. The credential health query may dispatch the already-installed `copilot_credential_health.yml` workflow, which creates an Actions run but does not modify repository configuration or expose Secret values. Only setup owns the separate temporary health-workflow bootstrap capability.

```bash
copilot doctor
copilot doctor --token "$SETUP_PAT"
copilot doctor --config .copilot-setup.yml --non-interactive
```

Existing GitHub Secret values cannot be read through the GitHub API. `copilot doctor` therefore dispatches `.github/workflows/copilot_credential_health.yml` when it is installed on the repository default branch. Each requested credential runs in its own job, so one invalid key does not make unrelated valid keys appear invalid. A present Secret without that workflow is reported as present but unverifiable; custom provider credentials are also reported as unverifiable until a provider-specific health check is available.

An override file can contain only non-secret values:

```yaml
features:
  inactiveIssueClosure: true
  release: false
  hotfix: false
agents:
  planner:
    provider: codex
    modelProvider: openai
    model: gpt-5.6-luna
  reviewer:
    provider: opencode
    modelProvider: anthropic
    model: claude-3-7-sonnet
    effort: high
repository:
  mainBranch: main
  developmentBranch: develop
  inactivityThresholdHours: 168
projects:
  ids: PVT_kwDOExample
  issueCreatedColumn: Todo
  issueInProgressColumn: In Progress
ai:
  bugbotSeverity: medium
  bugbotCommentLimit: 10
  bugbotEffort: smart
  bugbotDryRun: false
  bugbotReviewDrafts: false
  bugbotTraceRules: false
  bugbotSuggestedChanges: true
  bugbotTelemetry: true
  bugbotOrganizationRules: |-
    Require authorization checks on tenant-scoped operations
    Treat payment idempotency regressions as high severity
  ignoreFiles: node_modules/*,build/*,dist/*
  pullRequestDescriptionMode: append
createInitialTag: true
manageRepositoryVariables: true

# Secrets and Variables are configured independently. Organization resources
# require an organization-owned repository and organization Actions permissions.
storage:
  secrets:
    defaultScope: organization
    organizationVisibility: selected
    preserveExisting: true
  variables:
    defaultScope: repository
    preserveExisting: true
    overrides:
      OPENAI_API_KEY: organization
```

Run it with `copilot setup --config .copilot-setup.yml`. The wizard rejects values that look like tokens, API keys, passwords, or other credential material. Secret values are accepted only through the hidden prompt or explicit CLI inputs and are written directly to GitHub Secrets after validation; they are never written to repository files or Variables. The required secret names are shown in the final plan. They include `PAT` plus credentials that cannot be supplied by another approved mechanism; a Codex login already present on the target runner is an explicit alternative, so Codex API credentials remain optional fallbacks. When a repository already inherits an organization resource, `preserveExisting: true` avoids creating a repository shadow; use `storage.*.overrides` when one named resource needs a different scope.

### `copilot reconcile`

Checks whether the setup-managed workflow files in the current repository match the installed Copilot contract. It is read-only by default and does not call GitHub or change remote configuration. Use `--apply` to update only the detected setup-managed workflow files; those updates go through the same local backup/reconciliation path as setup.

```bash
copilot reconcile
copilot reconcile --json
copilot reconcile --apply
```

The first version deliberately scopes reconciliation to workflow templates. Branches, labels, Repository Variables, and Secrets remain under `copilot setup`/`copilot doctor` until their remote diff and approval contracts are added.

### `copilot check-progress`

Checks the progress of an issue from the selected branch and updates the progress label on the issue and its related open pull requests.

| Option | Required | Default | Description |
| --- | --- | --- | --- |
| `-i, --issue <number>` | Yes | — | Positive issue number. |
| `-b, --branch <name>` | No | Resolved from the issue | Branch to analyze. |
| `-t, --token <token>` | No | `PERSONAL_ACCESS_TOKEN` | PAT override. |
| `-d, --debug` | No | `false` | Enables debug logging. |
| `--dry-run` | No | `false` | Analyze and reconcile in memory without SCM mutations. |
| `--output <text\|json>` | No | `text` | Human-readable or machine-readable result. |
| `--effort <low\|default\|high\|smart>` | No | `smart` | Review depth policy. |
| `--trace-rules` | No | `false` | Include ordered rule sources. |
| `--no-suggestions` | No | suggestions enabled | Disable native suggested changes. |

```bash
copilot check-progress -i 123
copilot check-progress -i 123 -b feature/123-add-login
```

### `copilot detect-potential-problems`

Runs Bugbot against an issue and branch. Findings are published as issue comments when no PR exists, or as one summarized pull-request review when a PR is available.

| Option | Required | Default | Description |
| --- | --- | --- | --- |
| `-i, --issue <number>` | Yes | — | Positive issue number. |
| `-b, --branch <name>` | No | Current Git branch | Branch to analyze. |
| `-t, --token <token>` | No | `PERSONAL_ACCESS_TOKEN` | PAT override. |
| `-d, --debug` | No | `false` | Enables debug logging. |

The selected agent runtime, model, credentials, and Bugbot policy must be configured. See [Bugbot detection](/bugbot/detection).

```bash
copilot detect-potential-problems -i 456
copilot detect-potential-problems -i 456 -b feature/456-fix-bug --debug
copilot detect-potential-problems -i 456 --dry-run --output json --effort high
```

### Bugbot quality and analytics

`copilot bugbot-benchmark` runs the real configured findings agent sequentially against a versioned synthetic corpus and writes predictions. `copilot bugbot-eval` scores prediction files without calling a provider. `copilot bugbot-analytics` aggregates content-free Action telemetry from JSON, JSONL, or logs. See [Quality and observability](/bugbot/quality-observability).

### `copilot recommend-steps`

Uses the configured analysis agent to recommend implementation steps from an issue and posts the recommendation as an issue comment.

| Option | Required | Description |
| --- | --- | --- |
| `-i, --issue <number>` | Yes | Positive issue number. |
| `-t, --token <token>` | No | PAT override; otherwise uses `PERSONAL_ACCESS_TOKEN`. |
| `-d, --debug` | No | Enables debug logging. |

```bash
copilot recommend-steps -i 789
```

### `copilot think`

Runs deep code analysis and returns change proposals from the configured agent. The question is required; the issue and branch options provide repository context.

| Option | Required | Default | Description |
| --- | --- | --- | --- |
| `-q, --question <question...>` | Yes | — | Question or prompt. Multiple words may be supplied without shell quoting each word. |
| `-i, --issue <number>` | No | `1` | Issue number used when the repository has that issue context. |
| `-b, --branch <name>` | No | `master` | Branch to use for the analysis context. |
| `-t, --token <token>` | No | `PERSONAL_ACCESS_TOKEN` | PAT override. |
| `--ai-ignore-files <patterns>` | No | `node_modules/*,build/*` | Comma-separated file patterns excluded from AI context. |
| `--include-reasoning <true\|false>` | No | `false` | Include the agent's reasoning when supported by the configured flow. |
| `-d, --debug` | No | `false` | Enables debug logging. |

```bash
copilot think -q "Where is authentication validated?"
copilot think -i 123 -b feature/123-auth -q "Review the authentication flow"
```

### `copilot do`

Runs the configured **fixer/build agent** locally with a prompt. This is the CLI-only development assistant: it may edit files directly in the current workspace. It does not have a single-action equivalent and does not accept a GitHub PAT option.

| Option | Required | Default | Description |
| --- | --- | --- | --- |
| `-p, --prompt <prompt...>` | Yes | — | Request to execute in the current repository. |
| `--output <text\|json>` | No | `text` | Select human-readable or JSON output. |
| `--agent-provider <codex\|opencode\|cursor>` | No | `AGENT_PROVIDER` / `codex` | Runtime CLI override. |
| `--agent-model-provider <provider>` | No | `AGENT_MODEL_PROVIDER` | Model provider override. |
| `--agent-model <model>` | No | `AGENT_MODEL` | Model override. |
| `--agent-effort <effort>` | No | `AGENT_EFFORT` | Reasoning effort or provider-specific variant. |
| `--agent-executable <path>` | No | `AGENT_EXECUTABLE` | Exact provider basename or absolute executable path; no arguments. |
| `--findings-provider <provider>` | No | `FINDINGS_PROVIDER` | Findings task runtime override. |
| `--findings-model-provider <provider>` | No | `FINDINGS_MODEL_PROVIDER` | Findings model provider override. |
| `--findings-model <model>` | No | `FINDINGS_MODEL` | Findings model override. |
| `--findings-effort <effort>` | No | `FINDINGS_EFFORT` | Findings effort override. |
| `--findings-executable <path>` | No | `FINDINGS_EXECUTABLE` | Findings executable selection. |
| `--fixer-provider <provider>` | No | `FIXER_PROVIDER` | Fixer task runtime override. |
| `--fixer-model-provider <provider>` | No | `FIXER_MODEL_PROVIDER` | Fixer model provider override. |
| `--fixer-model <model>` | No | `FIXER_MODEL` | Fixer model override. |
| `--fixer-effort <effort>` | No | `FIXER_EFFORT` | Fixer effort override. |
| `--fixer-executable <path>` | No | `FIXER_EXECUTABLE` | Fixer executable selection. |
| `-d, --debug` | No | `false` | Enables debug logging. |

The primary agent values fall back to `AGENT_*` variables; task-specific values fall back to `FINDINGS_*` and `FIXER_*`. Credentials remain in the provider's supported environment or local credential store. Do not put credentials in command arguments or custom command values.

```bash
copilot do -p "Add tests for the authentication flow"
copilot do --output json -p "Explain the current release flow"
```

## Quick command summary

| CLI command | GitHub access | Required option | Main effect |
| --- | --- | --- | --- |
| `copilot setup` | PAT | — | Provision repository labels, types, templates, and workflows. |
| `copilot check-progress` | PAT | `-i, --issue` | Update progress from issue and branch changes. |
| `copilot detect-potential-problems` | PAT and agent | `-i, --issue` | Publish Bugbot findings. |
| `copilot bugbot-benchmark` | Agent | `--corpus`, `--predictions` | Generate real-agent corpus predictions. |
| `copilot bugbot-eval` | None | `--corpus`, `--predictions` | Score quality metrics and gates. |
| `copilot bugbot-analytics` | None | `--input` | Aggregate content-free telemetry. |
| `copilot recommend-steps` | PAT and agent | `-i, --issue` | Comment implementation recommendations. |
| `copilot think` | PAT and agent | `-q, --question` | Return analysis and change proposals. |
| `copilot do` | Agent only | `-p, --prompt` | Analyze or modify the local workspace. |

For the corresponding GitHub Action inputs, see [Available actions](/single-actions/available-actions). For provider credentials and model policy, see [Agent CLI configuration](/agents/cli-configuration).