{"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| `--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| `--model=MODEL` | Choose the AI model (for example, `gpt-5.2` or `claude-sonnet-4.6`). 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| `--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## 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 agentic memory for GitHub Copilot](/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.2`, `claude-sonnet-4.5`) |\n| `COPILOT_HOME` | Set the directory for the CLI configuration file (`~/.copilot` by default) |\n| `COPILOT_GITHUB_TOKEN` | Authentication token (highest precedence) |\n| `GH_TOKEN` | Authentication token (second precedence) |\n| `GITHUB_TOKEN` | Authentication token (third precedence) |\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> You can find the model strings for all available models in the description of the `--model` option when you enter `copilot help` in your terminal.\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/config.json` (or `$COPILOT_HOME/.copilot/config.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 \"reasoning_effort\": \"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/config.json` or `$COPILOT_HOME/.copilot/config.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)"}