{"meta":{"title":"About GitHub Copilot CLI","intro":"Find out about using Copilot from the command line.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/concepts","title":"Concepts"},{"href":"/en/copilot/concepts/agents","title":"Agents"},{"href":"/en/copilot/concepts/agents/copilot-cli","title":"Copilot CLI"},{"href":"/en/copilot/concepts/agents/copilot-cli/about-copilot-cli","title":"About Copilot CLI"}],"documentType":"article"},"body":"# About GitHub Copilot CLI\n\nFind out about using Copilot from the command line.\n\n## Introduction\n\nThe command-line interface (CLI) for GitHub Copilot allows you to use Copilot directly from your terminal. You can use it to answer questions, write and debug code, and interact with GitHub.com. For example, you can ask Copilot to make some changes to a project and create a pull request.\n\nGitHub Copilot CLI gives you quick access to a powerful AI agent, without having to leave your terminal. It can help you complete tasks more quickly by working on your behalf, and you can work iteratively with GitHub Copilot CLI to build the code you need.\n\n## Supported operating systems\n\n* Linux\n* macOS\n* Windows from within Powershell and [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/about)\n\nFor installation instructions, see [Installing GitHub Copilot CLI](/en/copilot/how-tos/set-up/install-copilot-cli).\n\n## Modes of use\n\nGitHub Copilot CLI has two user interfaces: interactive and programmatic.\n\n### Interactive interface\n\nTo start an interactive session, enter `copilot`. Within an interactive session, you can have a conversation with Copilot. You can prompt Copilot to perform one or more tasks, and you can give it feedback and steer the direction of the work.\n\n\n\nThe interactive interface has two modes. In addition to the default ask/execute mode there is also a **plan mode** in which Copilot will build a structured implementation plan for a task you want to complete.\n\nPress Shift+Tab to cycle between modes. In plan mode, Copilot analyzes your request, asks clarifying questions to understand scope and requirements, and builds a plan before writing any code. This helps you catch misunderstandings before any code is written, and stay in control of complex, multi-step tasks.\n\n### Programmatic interface\n\nYou can also pass the CLI a single prompt directly on the command line. The CLI completes the task and then exits.\n\nTo use the CLI programmatically, include the `-p` or `--prompt` command-line option in your command. To allow Copilot to modify and execute files you should also use one of the approval options described later in this article—see [Allowing tools to be used without manual approval](#allowing-tools-to-be-used-without-manual-approval) ). For example:\n\n```bash copy\ncopilot -p \"Show me this week's commits and summarize them\" --allow-tool='shell(git)'\n```\n\nAlternatively, you can use a script to output command-line options and pipe this to `copilot`. For example:\n\n```bash copy\n./script-outputting-options.sh | copilot\n```\n\n> \\[!CAUTION]\n> If you use an automatic approval option such as `--allow-all-tools`, Copilot has the same access as you do to files on your computer, and can run any shell commands that you can run, without getting your prior approval. See [Security considerations](#security-considerations), later in this article.\n\n## Use cases for GitHub Copilot CLI\n\nThe following sections provide examples of tasks you can complete with GitHub Copilot CLI.\n\n### Local tasks\n\n* From within a project directory you can ask Copilot to make a change to the code in the project. For example:\n\n `Change the background-color of H1 headings to dark blue`\n\n Copilot finds the CSS file where H1 headings are defined and changes the color value.\n\n* Ask Copilot to tell you about changes to a file:\n\n `Show me the last 5 changes made to the CHANGELOG.md file. Who changed the file, when, and give a brief summary of the changes they made`\n\n* Use Copilot to help you improve the code, or documentation, in your project.\n\n * `Suggest improvements to content.js`\n\n * `Rewrite the readme in this project to make it more accessible to newcomers`\n\n* Use Copilot to help you perform Git operations.\n\n * `Commit the changes to this repo`\n\n * `Revert the last commit, leaving the changes unstaged`\n\n* Ask Copilot to create an application from scratch—for example, as a proof of concept.\n\n `Use the create-next-app kit and tailwind CSS to create a next.js app. The app should be a dashboard built with data from the GitHub API. It should track this project's build success rate, average build duration, number of failed builds, and automated test pass rate. After creating the app, give me easy to follow instructions on how to build, run, and view the app in my browser.`\n\n* Ask Copilot to explain why a change it made is not working as expected, or tell Copilot to fix a problem with the last change it made. For example:\n\n `You said: \"The application is now running on http://localhost:3002 and is fully functional!\" but when I browse to that URL I get \"This site can't be reached\"`\n\n### Tasks involving GitHub.com\n\n* Fetch and display details about your work from GitHub.com.\n\n * `List my open PRs`\n\n This lists your open pull requests from any repository on GitHub. For more specific results, include the repository name in your prompt:\n\n * `List all open issues assigned to me in OWNER/REPO`\n\n* Ask Copilot to work on an issue:\n\n `I've been assigned this issue: https://github.com/octo-org/octo-repo/issues/1234. Start working on this for me in a suitably named branch.`\n\n* Ask Copilot to make file changes and raise a pull request on GitHub.com.\n\n * `In the root of this repo, add a Node script called user-info.js that outputs information about the user who ran the script. Create a pull request to add this file to the repo on GitHub.`\n\n * `Create a PR that updates the README at https://github.com/octo-org/octo-repo, changing the subheading \"How to run\" to \"Example usage\"`\n\n Copilot creates a pull request on GitHub.com, on your behalf. You are marked as the pull request author.\n\n* Ask Copilot to create an issue for you on GitHub.com.\n\n ``Raise an improvement issue in octo-org/octo-repo. In src/someapp/somefile.py the `file = open('data.txt', 'r')` block opens a file but never closes it.``\n\n* Ask Copilot to check the code changes in a pull request.\n\n `Check the changes made in PR https://github.com/octo-org/octo-repo/pull/57575. Report any serious errors you find in these changes.`\n\n Copilot responds in the CLI with a summary of any problems it finds.\n\n* Manage pull requests from GitHub Copilot CLI.\n\n * `Merge all of the open PRs that I've created in octo-org/octo-repo`\n\n * `Close PR #11 on octo-org/octo-repo`\n\n* Find specific types of issues.\n\n `Use the GitHub MCP server to find good first issues for a new team member to work on from octo-org/octo-repo`\n\n > \\[!NOTE]\n > If you know that a specific MCP server can achieve a particular task, then specifying it in your prompt can help Copilot to deliver the results you want.\n\n* Find specific GitHub Actions workflows.\n\n `List any Actions workflows in this repo that add comments to PRs`\n\n* Create a GitHub Actions workflow.\n\n `Branch off from main and create a GitHub Actions workflow that will run on pull requests, or can be run manually. The workflow should run eslint to check for problems in the changes made in the PR. If warnings or errors are found these should be shown as messages in the diff view of the PR. I want to prevent code with errors from being merged into main so, if any errors are found, the workflow should cause the PR check to fail. Push the new branch and create a pull request.`\n\n## Steering the conversation\n\nYou can interact with Copilot while it's thinking to steer the conversation:\n\n* **Enqueue additional messages**: Send follow-up messages to steer the conversation in a different direction, or queue additional instructions for Copilot to process after it finishes its current response. This makes conversations feel more natural and keeps you in control.\n* **Inline feedback on rejection**: When you reject a tool permission request, you can give Copilot inline feedback about the rejection so it can adapt its approach without stopping entirely. This makes the conversation flow more naturally when you want to guide Copilot away from certain actions.\n\n## Automatic context management\n\nGitHub Copilot CLI automatically manages your conversation context:\n\n* **Auto-compaction**: When your conversation approaches 95% of the token limit, Copilot automatically compresses your history in the background without interrupting your workflow. This enables virtually infinite sessions.\n* **Manual control**: Use `/compact` to manually compress context anytime. Press Escape to cancel if you change your mind.\n* **Visualize usage**: The `/context` command shows a detailed token usage breakdown so you can understand how your context window is being used.\n\n## Customizing GitHub Copilot CLI\n\nYou can customize GitHub Copilot CLI in a number of ways:\n\n* **Custom instructions**: Custom instructions allow you to give Copilot additional context on your project and how to build, test and validate its changes. All custom instruction files now combine instead of using priority-based fallbacks. For more information, see [Adding custom instructions for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions).\n* **Model Context Protocol (MCP) servers**: MCP servers allow you to give Copilot access to different data sources and tools. For more information, see [Using GitHub Copilot CLI](/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server).\n* **Custom agents**: Custom agents allow you to create different specialized versions of Copilot for different tasks. For example, you could customize Copilot to be an expert frontend engineer following your team's guidelines. GitHub Copilot CLI includes specialized custom agents that it automatically delegates common tasks to. For more information, see [Using GitHub Copilot CLI](/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents).\n* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. See [About hooks](/en/copilot/concepts/agents/cloud-agent/about-hooks).\n* **Skills**: Skills allow you to enhance the ability of Copilot to perform specialized tasks with instructions, scripts, and resources. For more information, see [About agent skills](/en/copilot/concepts/agents/about-agent-skills).\n* **Copilot Memory**: Copilot Memory allows Copilot to build a persistent understanding of your repository by storing \"memories\", which are pieces of information about coding conventions, patterns, and preferences that Copilot deduces as it works. This reduces the need to repeatedly explain context in your prompts and makes future sessions more productive. For more information, see [About agentic memory for GitHub Copilot](/en/copilot/concepts/agents/copilot-memory).\n\n## Security considerations\n\nWhen you use Copilot CLI, Copilot can perform tasks on your behalf, such as executing or modifying files, or running shell commands.\n\nYou should therefore always keep security considerations in mind when using Copilot CLI, just as you would when working directly with files yourself, or running commands directly in your terminal. You should always review suggested commands carefully when Copilot CLI requests your approval.\n\n### Trusted directories\n\nTrusted directories control where Copilot CLI can read, modify, and execute files.\n\nYou should only launch Copilot CLI from directories that you trust. You should not use Copilot CLI in directories that may contain executable files you can't be sure you trust. Similarly, if you launch the CLI from a directory that contains sensitive or confidential data, or files that you don't want to be changed, you could inadvertently expose those files to risk. Typically, you should not launch Copilot CLI from your home directory.\n\nScoping of permissions is heuristic and GitHub does not guarantee that all files outside trusted directories will be protected. See [Risk mitigation](#risk-mitigation).\n\nWhen you start a GitHub Copilot CLI session, you'll be asked to confirm that you trust the files in, and below, the directory from which you launched the CLI. See [Configuring GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli#setting-trusted-directories).\n\n### Allowed tools\n\nThe first time that Copilot needs to use a tool that could be used to modify or execute a file—for example, `touch`, `chmod`, `node`, or `sed`—it will ask you whether you want to allow it to use that tool.\n\nTypically, you can choose from three options:\n\n```text\n1. Yes\n2. Yes, and approve TOOL for the rest of the running session\n3. No, and tell Copilot what to do differently (Esc)\n```\n\n**Option 1** allows Copilot to run this particular command, this time only. The next time it needs to use this tool, it will ask you again.\n\n**Option 2** allows Copilot to use this tool again, without asking you for permission, for the duration of the currently running session. It will ask for your approval again in new sessions, or if you resume the current session in the future. If you choose this option, you are allowing Copilot to use this tool in any way it thinks is appropriate. For example, if Copilot asks you to allow it to run the command `rm ./this-file.txt`, and you choose option 2, then Copilot can run any `rm` command (for example, `rm -rf ./*`) during the current run of this session, without asking for your approval.\n\n**Option 3** cancels the proposed command and allows you to tell Copilot to try a different approach.\n\n#### Allowing tools to be used without manual approval\n\nThere are three command-line options that you can use, in either interactive or programmatic sessions, to determine tools that Copilot can use without asking for your approval:\n\n* **`--allow-all-tools`**\n\n Allows Copilot to use any tool without asking for your approval.\n\n For example, you can use this option with a programmatic invocation of the CLI to allow Copilot to run any command. For example:\n\n ```shell\n copilot -p \"Revert the last commit\" --allow-all-tools\n ```\n\n* **`--deny-tool`**\n\n Prevents Copilot from using a specific tool.\n\n This option takes precedence over the `--allow-all-tools` and `--allow-tool` options.\n\n* **`--allow-tool`**\n\n Allows Copilot to use a specific tool without asking for your approval.\n\n#### Using the approval options\n\nThe `--deny-tool` and `--allow-tool` options require one of the following arguments:\n\n* `'shell(COMMAND)'`\n\n For example, `copilot --deny-tool='shell(rm)'` prevents Copilot from using any `rm` command.\n\n For `git` and `gh` commands, you can specify a particular first-level subcommand to allow or deny. For example:\n\n ```shell\n copilot --deny-tool='shell(git push)'\n ```\n\n The tool specification is optional. For example, `copilot --allow-tool='shell'` allows Copilot to use any shell command without individual approval.\n\n* `'write'`\n\n This argument allows or denies tools—other than shell commands—permission to modify files.\n\n For example, `copilot --allow-tool='write'` allows Copilot to edit files without your individual approval.\n\n* `'MCP_SERVER_NAME'`\n\n This argument allows or denies tools from the specified MCP server, where `MCP_SERVER_NAME` is the name of an MCP server that you have configured. Tools from the server are specified in parentheses, using the tool name that is registered with the MCP server. Using the server name without specifying a tool allows or denies all tools from that server.\n\n For example, `copilot --deny-tool='My-MCP-Server(tool_name)'` prevents Copilot from using the tool called `tool_name` from the MCP server called `My-MCP-Server`.\n\n You can find an MCP server's name by entering `/mcp` in the CLI's interactive interface, then selecting the server from the list that's displayed.\n\n#### Combining approval options\n\nYou can use a combination of approval options to determine exactly which tools Copilot can use without asking for your approval.\n\nFor example, to prevent Copilot from using the `rm` and `git push` commands, but automatically allow all other tools, use:\n\n```shell\ncopilot --allow-all-tools --deny-tool='shell(rm)' --deny-tool='shell(git push)'\n```\n\nTo prevent Copilot from using the tool `tool_name` from the MCP server named `My-MCP-Server`, but allow all other tools from that server to be used without individual approval, use:\n\n```shell\ncopilot --allow-tool='My-MCP-Server' --deny-tool='My-MCP-Server(tool_name)'\n```\n\n#### Security implications of automatic tool approval\n\nIt's important to be aware of the security implications of using the approval command-line options. These options allow Copilot to execute commands needed to complete your request, without giving you the opportunity to review and approve those commands before they are run. While this streamlines workflows, and allows headless operation of the CLI, it increases the risk of unintended actions being taken that might result in data loss or corruption, or other security issues.\n\nYou can control which tools Copilot CLI can use by responding to approval prompts when Copilot attempts to use a tool, by specifying permissions with command-line flags, or (in an interactive session) by using slash commands (such as `/allow-all` and `/yolo`. See [Configuring GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli#setting-allowed-tools).\n\n### Risk mitigation\n\nYou can mitigate the risks associated with using the automatic approval options by running Copilot CLI in a restricted environment—such as a virtual machine, container, or dedicated system—with tightly controlled permissions and network access. This confines any potential damage that could occur when allowing Copilot to execute commands that you have not reviewed and verified.\n\n### Known MCP server policy limitations\n\nCopilot CLI can't currently support the following organization-level MCP server policies:\n\n* **MCP servers in Copilot**, which controls whether MCP servers can be used at all by Copilot.\n* **MCP Registry URL**, which controls which MCP registry Copilot will allow MCP servers to be used from.\n\nFor more information about these policies, see [MCP server usage in your company](/en/copilot/concepts/mcp-management#mcp-policy-settings).\n\n## Model usage\n\nThe default model used by GitHub Copilot CLI is Claude Sonnet 4.5. GitHub reserves the right to change this model.\n\nYou can change the model used by GitHub Copilot CLI by using the `/model` slash command or the `--model` command-line option. Enter this command, then select a model from the list.\n\nEach time you submit a prompt to Copilot in Copilot CLI's interactive interface, and each time you use Copilot CLI programmatically, your monthly quota of Copilot premium requests is reduced by one, multiplied by the multiplier shown in parentheses in the model list. For example, `Claude Sonnet 4.5 (1x)` indicates that with this model each time you submit a prompt your quota of premium requests is reduced by one. For information about premium requests, see [Requests in GitHub Copilot](/en/copilot/concepts/billing/copilot-requests).\n\n### Using your own model provider\n\nYou can configure Copilot CLI to use your own model provider instead of GitHub-hosted models. This lets you connect to an OpenAI-compatible endpoint, Azure OpenAI, or Anthropic, including locally running models such as Ollama. You configure your model provider using environment variables.\n\n| Environment variable | Description |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `COPILOT_PROVIDER_BASE_URL` | The base URL of your model provider's API endpoint. |\n| `COPILOT_PROVIDER_TYPE` | The provider type: `openai` (default), `azure`, or `anthropic`. The `openai` type works with any OpenAI-compatible endpoint, including Ollama and vLLM. |\n| `COPILOT_PROVIDER_API_KEY` | Your API key for authenticating with the provider. Not required for providers that don't use authentication, such as a local Ollama instance. |\n| `COPILOT_MODEL` | The model to use (required when using a custom provider). You can also set this with the `--model` command-line option. |\n\nModels used with Copilot CLI must support **tool calling** (function calling) and **streaming**. If the model does not support these capabilities, Copilot CLI will return an error. For best results, the model should have a context window of at least 128k tokens.\n\nFor details on how to configure your model provider, run `copilot help providers` in your terminal.\n\n## Use Copilot CLI via ACP\n\nACP (the Agent Client Protocol) is an open standard for interacting with AI agents. It allows you to use Copilot CLI as an agent in any third-party tools, IDEs, or automation systems that support this protocol.\n\nFor more information, see [Copilot CLI ACP server](/en/copilot/reference/copilot-cli-reference/acp-server).\n\n## Feedback\n\nIf you have any feedback about GitHub Copilot CLI, please let us know by using the `/feedback` slash command in an interactive session and choosing one of the options. You can complete a private feedback survey, submit a bug report, or suggest a new feature.\n\n## Further reading\n\n* [Installing GitHub Copilot CLI](/en/copilot/how-tos/set-up/install-copilot-cli)\n* [Using GitHub Copilot CLI](/en/copilot/how-tos/use-copilot-agents/use-copilot-cli)\n* [Responsible use of GitHub Copilot CLI](/en/enterprise-cloud@latest/copilot/responsible-use/copilot-cli)"}