Copilot CLI
See the generated compatibility matrix for capability details and version-scoped evidence.
copilot-cli runs ctrlyoke workflows through the GitHub Copilot CLI while keeping the same workflow file format used elsewhere.

Good fit
- Teams that already have a GitHub Copilot subscription and use the Copilot CLI
- Workflows that want Copilot's model catalog behind the ctrlyoke queue, history, and script gating
Prerequisites
- Command:
copilot, on yourPATH. - Install: see Install.
- Sign in: run
copilotonce in a terminal and sign in with/login. - Version: at least the minimum listed under Supported versions. Update with
copilot update.
If the CLI is missing, the harness picker shows a red dot next to Copilot CLI, and its tooltip gives the install command. If it is installed but older than the minimum, it still runs: the picker shows an amber dot and the update command, a workflow that uses it warns when it starts, and a failed step repeats that command. After installing or updating, click Retry harness detection in the harness picker. If no harness CLI is available at all, the dashboard shows a No CLI coding agent is available panel with the install command for every harness.
Install
Install the GitHub Copilot CLI with GitHub's installer:
macOS and Linux:
curl -fsSL https://gh.io/copilot-install | bashWindows (PowerShell):
winget install GitHub.CopilotHomebrew (brew install copilot-cli) and npm (npm install -g @github/copilot) also work. Windows needs PowerShell 6 or newer.
See GitHub's install guide for other install methods.
Example
harness: copilot-cli
model: claude-sonnet-5.5
steps:
- prompt: Review @src/ for the highest-priority reliability issue.Headless prompts
In headless steps, ctrlyoke pipes the prompt to Copilot's stdin and requests JSON output. Generated sections such as agent instructions, skills and prior-step context are included in that first message so Copilot can use them immediately. Turn off execution.inlineGeneratedPromptOnStdin to use categorized temporary files and references instead.
Model selection
The Model picker lists the models that copilot help config reports. ctrlyoke reads that list when it starts, so reload the window after Copilot adds a model. If the command fails, ctrlyoke uses its built-in list instead.
Set model on the workflow or on a step. Without one, ctrlyoke uses defaults.models["copilot-cli"], which is none out of the box: no --model flag is passed, so Copilot uses its own default model, which is always one your account can use. A model that isn't on the list is replaced by your default, with a warning in the log; if the default is none, no --model flag is passed. The ctrlyoke CLI doesn't look the list up, so it passes the model to Copilot as you wrote it.
model: none passes no --model flag, so Copilot uses its own default model. copilot help config sometimes lags behind the models Copilot accepts; to use one it doesn't list yet, set model: none and pass --model <id> in additionalArgs. See How step properties inherit.
Permissions
Copilot does not support ctrlyoke's sandbox property. An explicit sandbox: true fails the step at launch: Copilot's per-run sandbox also contains ctrlyoke's MCP server and hooks, preventing them from running, and its policy can only be configured in the user's settings. A true inherited from defaults.sandbox only warns. false passes --no-sandbox, which turns off a sandbox you enabled in Copilot's own settings; an organization policy that requires the sandbox still applies. null passes nothing. See Sandboxing.
The permission mode maps to Copilot flags:
dangerouslyAllowAll→--yolo. The deny list is ignored.allowAll→--allow-all-tools, plus--deny-toolwith the deny listauto→ headless only:--assisted-approval, plus allow and deny rules. Interactive runs fall back tocustom; enable Copilot's assisted mode with/permissions assistedordefaultPermissionMode: "assisted"in Copilot settings.custom→--allow-toolwith the allow list, plus--deny-toolwith the deny listnone→ no permission flags (Copilot's own configuration)
Copilot uses the same pattern syntax as ctrlyoke, so patterns pass through unchanged: the default deny list reaches Copilot as --deny-tool shell(rm:*) shell(git push:*) …. Two exceptions:
- MCP patterns are rewritten to Copilot's form:
mcp__github__create_issuebecomesgithub(create_issue). - Read-only tools (
read,read_file,grep,list_filesandsearch_files) are dropped from both lists, because Copilot always allows them.
See Permissions for the modes, the pattern syntax and the default lists.
Notes
- Directories outside the workspace are granted through
permissions.trustedExternalRoots; ctrlyoke passes each approved root to Copilot as--add-dir. To pass--allow-all-pathsinstead, add it todefaults.additionalArgs["copilot-cli"]. - If you need a workflow to continue a previous Copilot conversation, use
resumeSessionorsessionId. - Before resuming, ctrlyoke checks Copilot's local session store by ID. If the transcript is missing, it starts a new conversation and shows a warning in that step's output.
- Copilot has no command-line option for hooks, so ctrlyoke writes a hook file for each step to
.github/hooks/and removes it afterwards. See Files ctrlyoke writes.
Usage and rate limits
Copilot reports your account's monthly quota: premium requests or AI credits, depending on your plan (labelled Premium interactions when Copilot doesn't say which), plus chat and completions on plans that cap them. ctrlyoke asks the Copilot CLI for it directly, without starting a session or using a model turn, so it is available between runs too. Run ctrlyoke: Refresh Harness Usage to fetch it again.
The context-window bar on each step comes from Copilot's OpenTelemetry export, which ctrlyoke turns on for every Copilot process it starts.
Quota percentages appear next to the harness in the harness picker, with the reset time in its tooltip, and on the Stats & Usage settings tab. If a queued step's harness is above usageTracking.warningPercentUsed (80% by default), ctrlyoke warns when the run starts but doesn't stop it. Turn collection off with usageTracking.enabled.
Status line
ctrlyoke changes your global Copilot settings: the first time it runs Copilot, it points the statusLine key in ~/.copilot/settings.json at its own status line command, so Copilot's terminal UI shows the model, context and usage. The change stays in place between runs, in every project. If you already had a status line command, ctrlyoke keeps running it underneath.
To undo it, turn Copilot off in Settings → Status Line. ctrlyoke then puts your original command back. See Files ctrlyoke writes.
Sign-in problems
If your Copilot sign-in expires during a run, the next step that starts Copilot fails, and the workflow stops unless errorBehavior retries it. A headless step shows Copilot's error in its output; for an interactive step, look at the Terminal tab. Retries fail the same way until you sign in again. When ctrlyoke's quota check finds you signed out, Copilot's tooltip in the harness picker reads Needs auth instead of a quota.
To recover, run copilot in a terminal and sign in with /login, then click Resume in the dashboard to retry the failed step.
From the ctrlyoke CLI, a sign-in failure exits with code 1, not 3. ctrlyoke can't tell an expired sign-in from any other error Copilot reports, so it counts as a failed step. Code 3 means only that the copilot executable wasn't found. See Exit codes, and Harness sign-in for CI runners.