{"meta":{"title":"GitHub Copilot CLI programmatic reference","intro":"Find options for running Copilot CLI programmatically.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/reference","title":"Reference"},{"href":"/en/copilot/reference/copilot-cli-reference","title":"Copilot CLI reference"},{"href":"/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference","title":"CLI programmatic reference"}],"documentType":"article"},"body":"# GitHub Copilot CLI programmatic reference\n\nFind options for running Copilot CLI programmatically.\n\nIn addition to running Copilot CLI interactively, you can also pass a prompt directly to the CLI in a single command, without entering an interactive session. This allows you to use Copilot programmatically in scripts, CI/CD pipelines, and automation workflows. For more information, see [Running GitHub Copilot CLI programmatically](/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically).\n\nThis article describes command-line options and environment variables that are particularly relevant when running Copilot CLI programmatically.\n\nTo see a complete list of the available options, see [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options) or enter the following command in your terminal:\n\n```shell copy\ncopilot help\n```\n\n## Command line options\n\nThere are a number of command-line options that are particularly useful when running Copilot CLI programmatically.\n\n| Option | Description |\n| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `-p PROMPT` | Execute a prompt in non-interactive mode. The CLI runs the prompt and exits when done. |\n| `-s` | Suppress stats and decoration, outputting only the agent's response. Ideal for piping output in scripts. |\n| `--add-dir=DIRECTORY` | Add a directory to the allowed-paths list. This can be used multiple times to add multiple directories. Useful when the agent needs to read/write outside the current working directory. |\n| `--agent=AGENT` | Specify a custom agent to use. |\n| `--allow-all` (or `--yolo`) | Allow the CLI all permissions. Equivalent to `--allow-all-tools --allow-all-paths --allow-all-urls`. |\n| `--allow-all-paths` | Disable file-path verification entirely. Simpler alternative to `--add-dir` when path restrictions aren't needed. |\n| `--allow-all-tools` | Allow every tool to run without explicit permission for each tool. |\n| `--allow-all-urls` | Allow access to all URLs without explicit permission for each URL. |\n| `--allow-tool=TOOL ...` | Selectively grant permission for a specific tool. For multiple tools, use a quoted, comma-separated list. |\n| `--allow-url=URL ...` | Allow the agent to fetch a specific URL or domain. Useful when a workflow needs web access to known endpoints. For multiple URLs, use a quoted, comma-separated list. |\n| `--attachment=PATH ...` | Attach a file (image or native document) to the initial prompt. Only valid in non-interactive mode. Can be used multiple times to attach multiple files. |\n| `--available-tools=TOOL ...` | Restrict the model to only the tools you list; all other tools are unavailable. Useful for tightly scoping what the agent can do in an automated workflow. For multiple tools, use a quoted, comma-separated list. |\n| `--deny-tool=TOOL ...` | Deny a specific tool. Useful for restricting what the agent can do in a locked-down workflow. For multiple tools, use a quoted, comma-separated list. |\n| `--deny-url=URL ...` | Deny access to a specific URL or domain. Takes precedence over `--allow-url`. For multiple URLs, use a quoted, comma-separated list. |\n| `--excluded-tools=TOOL ...` | Remove specific tools from those available to the model. For multiple tools, use a quoted, comma-separated list. |\n| `--fleet` | Run the prompt in fleet mode, so Copilot uses parallel subagents to work on separate parts of the task. Combine with `-p` for non-interactive automation, `-i` for an interactive session, or a piped prompt. Not supported in ACP server mode. See [Speeding up task completion with the \\`/fleet\\` command](/en/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion). |\n| `--model=MODEL` | Choose the AI model (for example, `gpt-5.4` or `claude-haiku-4.5`). Useful for pinning a model in reproducible workflows. See [Choosing a model](#choosing-a-model) below. |\n| `--no-ask-user` | Prevent the agent from pausing to seek additional user input. |\n| `--output-format=FORMAT` | Set the output format: `text` (the default) or `json`. With `json`, the CLI emits JSONL (one JSON object per line), which is convenient for parsing the agent's output in scripts. |\n| `--secret-env-vars=VAR ...` | An environment variable whose value you want redacted in output. For multiple variables, use a quoted, comma-separated list. Essential for preventing secrets being exposed in logs. The values in the `GITHUB_TOKEN` and `COPILOT_GITHUB_TOKEN` environment variables are redacted by default. |\n| `--share=PATH` | Export the session transcript to a markdown file after non-interactive completion (defaults to `./copilot-session-.md`). Useful for auditing or archiving what the agent did. Note that session transcripts may contain sensitive information. |\n| `--share-gist` | Publish the session transcript as a secret GitHub gist after completion. Convenient for sharing results from CI. Note that session transcripts may contain sensitive information. |\n\n## Running dynamic workflows\n\nUse `copilot workflow run WORKFLOW-NAME` to run a dynamic workflow from a script. To find out about dynamic workflows, see [Dynamic workflows](/en/copilot/concepts/agents/dynamic-workflows).\n\nUse `--args` for inline JSON or an `@`-prefixed JSON file path. Arguments are not read from standard input.\n\n```shell copy\ncopilot workflow run WORKFLOW-NAME \\\n --args @workflow-input.json \\\n --silent --output-format json\n```\n\nConfigure authentication and grant the required tool permissions before running the command. Shared options such as `--model`, `--allow-tool`, `--allow-url`, and `--add-dir` apply. The command does not display permission approval prompts. Prompt and session-mode options such as `-p`, `-i`, `--agent`, `--fleet`, `--autopilot`, `--resume`, and `--continue` are not supported with `workflow run`.\n\nProject extensions are loaded only from trusted folders or with an explicit opt-in. In automation, `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true` permits loading project extensions for that invocation. Only enable this for repository code you trust. It does not grant tool permissions.\n\nFor all workflow-specific options, see [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-workflow-run).\n\n### Workflow output\n\nWith `--output-format json`, standard output uses JSONL. When the run finishes or stops, the final record has the following fields. Add `--silent` to suppress progress and other event records.\n\n| Field | Description |\n| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `type` | Always `workflow.result`. |\n| `data.name` | The workflow name. |\n| `data.run.runId` | The run's identifier. |\n| `data.run.status` | The final run status: `completed`, `halted`, `paused`, `cancelled`, or `error`. |\n| `data.run.result` | The returned value, if any. Omitted when `--result-file` is supplied. |\n| `data.run.pauseInfo`, `data.run.reason`, `data.run.error`, `data.run.failure` | Additional details about why a run paused or stopped, when available. |\n| `data.resultFile` | The requested result-file path, included only after the result file has been written successfully. |\n\nWith `--result-file PATH`, the file contains only the returned value, as JSON. A paused, failed, or interrupted run does not replace an existing result file. A completed run that returns no value does not write a result file.\n\nErrors and diagnostics for runs that do not complete are written to standard error, including in silent mode. An error before the workflow starts, or an interruption, can end the command without a final JSON record.\n\n### Workflow exit codes\n\n| Exit code | Meaning |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `0` | The workflow completed successfully and any requested result file was written successfully. A workflow that returns no value can also complete successfully without creating a result file. |\n| `1` | The run did not complete, including a pause, a limit that stopped the run, cancellation, or failure. Also used for general command errors, such as invalid command-line syntax or a failure to save the result. |\n| `2` | The workflow was not found, or its arguments could not be read, parsed as JSON, or validated against the workflow's accepted inputs. |\n| `130` | The command was interrupted by `SIGINT` or `SIGTERM`, for example by pressing Ctrl+C. |\n\nCheck the exit code before consuming a result file. An earlier result file may still exist after an unsuccessful run. A final record with `data.run.status` set to `completed` does not guarantee the result file was saved successfully.\n\n## Tools for the `--allow-tool` option\n\nYou can specify various kinds of tools with the `--allow-tool` option.\n\n| Kind of tool | What it controls |\n| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| shell | Executing shell commands. |\n| write | Creating or modifying files. |\n| read | Reading files or directories. |\n| url | Fetching content from a URL. |\n| memory | Storing new facts to the agent's persistent memory. This does not affect using existing memories. See [About GitHub Copilot Memory](/en/copilot/concepts/agents/copilot-memory). |\n| MCP-SERVER | Invoking tools from a specific MCP server. Use the server's configured name as the identifier—for example, `github`. See [Adding MCP servers for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). |\n\n### Tool filters\n\nThe `shell`, `write`, `url`, and MCP server tool kinds allow you to specify a filter, in parentheses, to control which specific tools are allowed.\n\n\n\n| Kind of tool | Example | Explanation of the example |\n| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------- |\n| **shell** | `shell(git:*)` | Allow all Git subcommands (`git push`, `git status`, etc.). |\n| | `shell(npm test)` | Allow the exact command `npm test`. |\n| **write** | `write(.github/copilot-instructions.md)` | Allow the CLI to write to this specific path. |\n| | `write(README.md)` | Allow the CLI to write to any file whose path ends with `/README.md`. |\n| **url** | `url(github.com)` | Allow the CLI to access HTTPS URLs on github.com. |\n| | `url(http://localhost:3000)` | Allow the CLI to access the local dev server with explicit protocol and port. |\n| | `url(https://*.github.com)` | Allow the CLI to access any GitHub subdomain (for example, `api.github.com`). |\n| | `url(https://docs.github.com/copilot/*)` | Allow access to Copilot documentation at this site. |\n| **MCP-SERVER** | `github(create_issue)` | Allow only the `create_issue` tool from the `github` MCP server. |\n\n\n\n> \\[!NOTE]\n> Wildcards are only supported for `shell` to match all subcommands of a specified tool, and for `url` at the start of the host name to match any subdomain, or at the end of a path to match any path suffix—as shown in the preceding table.\n\n## Environment variables\n\nYou can use environment variables to configure various aspects of the CLI's behavior when running programmatically. This is particularly useful for setting configuration in CI/CD workflows or other automated environments where you may not want to specify certain options directly in the command line.\n\n| Variable | Description |\n| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `COPILOT_ALLOW_ALL` | Set to `true` for full permissions |\n| `COPILOT_MODEL` | Set the model (for example, `gpt-5.4`, `claude-haiku-4.5`) |\n| `COPILOT_HOME` | Set the directory for the CLI configuration file (`~/.copilot` by default) |\n| `COPILOT_AUTO_UPDATE` | Set to `false` to disable automatic updates. Useful in CI and other automated environments where you want to pin the CLI version. |\n| `COPILOT_GITHUB_TOKEN` | Authentication token (highest precedence) |\n| `GH_TOKEN` | Authentication token (second precedence) |\n| `GITHUB_TOKEN` | Authentication token (third precedence) |\n| `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | Set to `true` to allow project extensions to load for a prompt or direct workflow run. Only use this for repository code you trust. This does not grant tool permissions. |\n\nFor full details of environment variables for Copilot CLI, use the command `copilot help environment` in your terminal.\n\n## Choosing a model\n\nWhen you send a prompt to Copilot CLI in non-interactive mode, the model that the CLI uses to generate a response is shown in the response output (if the `-s`, or `--silent`, option is not used).\n\nYou can use the `--model` option to specify which AI model the CLI should use. This allows you to choose a model that is best suited to your prompt, balancing factors like speed, cost, and capability.\n\nFor example, for straightforward tasks, such as explaining some code or generating a summary, you might choose a fast, lower cost model such as a Claude Haiku model:\n\n```bash copy\ncopilot -p \"What does this project do?\" -s --model claude-haiku-4.5\n```\n\nFor more complex tasks that require deeper reasoning—such as debugging or refactoring code—you might choose a more powerful model, such as a GPT Codex model:\n\n```bash copy\ncopilot -p \"Fix the race condition in the worker pool\" \\\n --model gpt-5.3-codex \\\n --allow-tool='write, shell'\n```\n\n> \\[!NOTE]\n> To see the model strings for all available models, run the `/model` command in an interactive Copilot CLI session. For the full list of models and the clients that support them, see [Supported AI models in GitHub Copilot](/en/copilot/reference/ai-models/supported-models).\n\nAlternatively, you can set the `COPILOT_MODEL` environment variable to specify a model for the duration of the shell session.\n\nTo persist a model selection across shell sessions, you can set the `model` key in the CLI configuration file. This file is located at `~/.copilot/settings.json` (or `$COPILOT_HOME/settings.json` if you have set the `COPILOT_HOME` environment variable). Some models also allow you to set a reasoning effort level, which controls how much time the model spends thinking before responding.\n\n```json copy\n{\n \"model\": \"gpt-5.3-codex\",\n \"effortLevel\": \"low\"\n}\n```\n\n> \\[!TIP]\n> The easiest way to set a model persistently in the configuration file is with the `/model` slash command in an interactive session. The choice you make with this command is written to the configuration file.\n\n### Model precedence\n\nWhen determining which model to use for a given prompt, the CLI checks for model specifications in the following order of precedence (from highest to lowest):\n\n* Where a custom agent is used: the model specified in the custom agent definition (if any).\n* The `--model` command line option.\n* The `COPILOT_MODEL` environment variable.\n* The `model` key in the configuration file (`~/.copilot/settings.json` or `$COPILOT_HOME/settings.json`).\n* The CLI's default model.\n\n## Using custom agents\n\nYou can delegate work to a specialized agent by using the `--agent` option. For more information, see [Creating and using custom agents for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli).\n\nIn this example, the `code-review` agent is used. This requires that a custom agent has been created with this name.\n\n```bash\ncopilot -p \"Review the latest commit\" \\\n --allow-tool='shell' \\\n --agent code-review\n```\n\n## Further reading\n\n* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference)"}