{"meta":{"title":"Running GitHub Copilot CLI programmatically","intro":"Use Copilot CLI in the terminal, in scripts, or in Actions workflows.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/how-tos","title":"How-tos"},{"href":"/en/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/en/copilot/how-tos/copilot-cli/automate-copilot-cli","title":"Automate with Copilot CLI"},{"href":"/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically","title":"Run the CLI programmatically"}],"documentType":"article"},"body":"# Running GitHub Copilot CLI programmatically\n\nUse Copilot CLI in the terminal, in scripts, or in Actions workflows.\n\n## Introduction\n\nYou can pass a prompt directly to Copilot CLI in a single command, without entering an interactive session. This allows you to use Copilot directly from the terminal, but also allows you to use the CLI programmatically in scripts, CI/CD pipelines, and automation workflows.\n\nTo use Copilot CLI programmatically you can do either of the following.\n\n* Use the `copilot` command with the `-p` or `--prompt` command-line option, followed by your prompt:\n\n  ```shell copy\n  copilot -p \"Explain this file: ./complex.ts\"\n  ```\n\n* Pipe a prompt to the `copilot` command:\n\n  ```shell copy\n  echo \"Explain this file: ./complex.ts\" | copilot\n  ```\n\n  > \\[!NOTE]\n  > Piped input is ignored if you also provide a prompt with the `-p` or `--prompt` option.\n\n## Tips for using Copilot CLI programmatically\n\n* **Provide precise prompts** — clear, unambiguous instructions produce better results than vague requests. The more context you give—file names, function names, the exact change—the less guesswork Copilot has to do.\n* **Quote prompts carefully** — use single quotes around your prompt if you want to avoid shell interpretation of special characters.\n* **Always give minimal permissions** — use the `--allow-tool=[TOOLS...]` and `--allow-url=[URLs...]` command-line options to give Copilot permission to use only the tools and access that are necessary to complete the task. Avoid using overly permissive options (such as `--allow-all`) unless you are working in a sandbox environment. For more information, see [About cloud and local sandboxes for GitHub Copilot](/en/copilot/concepts/about-cloud-and-local-sandboxes).\n* **Use `-s` (silent)** when capturing output. This suppresses session metadata so you get clean text.\n* **Use `--no-ask-user`** to prevent the agent from attempting to ask clarifying questions.\n* **Set a model explicitly** with `--model` for consistent behavior across environments.\n\nSee [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference) for options that are particularly useful when running Copilot CLI programmatically.\n\n## CI/CD integration\n\nA common use case for running Copilot CLI programmatically is to include a CLI command in a CI/CD workflow step.\n\nThis extract from a GitHub Actions workflow shows a simple example of running a Copilot CLI command.\n\n```yaml\n# Workflow step using Copilot CLI\n- name: Generate test coverage report\n  env:\n    COPILOT_GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}\n  run: |\n    copilot -p \"Run the test suite and produce a coverage summary\" \\\n      -s --allow-tool='shell(npm:*), write' --no-ask-user\n```\n\nFor more information, see [Automating tasks with Copilot CLI and GitHub Actions](/en/copilot/how-tos/copilot-cli/automate-copilot-cli/automate-with-actions).\n\n## Examples of programmatic usage\n\n### Generate a commit message\n\n```bash copy\ncopilot -p 'Write a commit message in plain text for the staged changes' -s \\\n  --allow-tool='shell(git:*)'\n```\n\n### Summarize a file\n\n```bash copy\ncopilot -p 'Summarize what src/auth/login.ts does in no more than 100 words' -s\n```\n\n### Write tests for a module\n\n```bash copy\ncopilot -p 'Write unit tests for src/utils/validators.ts' \\\n  --allow-tool='write, shell(npm:*), shell(npx:*)'\n```\n\n### Fix lint errors\n\n```bash copy\ncopilot -p 'Fix all ESLint errors in this project' \\\n  --allow-tool='write, shell(npm:*), shell(npx:*), shell(git:*)'\n```\n\n### Explain a diff\n\n```bash copy\ncopilot -p 'Explain the changes in the latest commit on this branch and flag any potential issues' -s\n```\n\n### Code review a branch\n\nUse `/review` slash command to have the built-in `code-review` agent review the code changes on the current branch.\n\n```bash copy\ncopilot -p '/review the changes on this branch compared to main. Focus on bugs and security issues.' \\\n  -s --allow-tool='shell(git:*)'\n```\n\n### Generate documentation\n\n```bash copy\ncopilot -p 'Generate JSDoc comments for all exported functions in src/api/' \\\n  --allow-tool=write\n```\n\n### Export a session\n\nSave the full session transcript to a Markdown file on the local filesystem.\n\n```bash copy\ncopilot -p \"Audit this project's dependencies for vulnerabilities\" \\\n  --allow-tool='shell(npm:*), shell(npx:*)' \\\n  --share='./audit-report.md'\n```\n\nSave the session transcript to a gist on GitHub.com for easy sharing.\n\n```bash copy\ncopilot -p 'Summarize the architecture of this project' --share-gist\n```\n\n> \\[!NOTE]\n> Gists are not available to Enterprise Managed Users, or if you use GitHub Enterprise Cloud with data residency (\\*.ghe.com).\n\n## Shell scripting patterns\n\n### Capture Copilot's output in a variable\n\n```bash copy\nresult=$(copilot -p 'What version of Node.js does this project require? \\\n  Give the number only. No other text.' -s)\necho \"Required Node version: $result\"\n```\n\n### Use in a conditional\n\n```bash copy\nif copilot -p 'Does this project have any TypeScript errors? Reply only YES or NO.' -s \\\n  | grep -qi \"no\"; then\n  echo \"No type errors found.\"\nelse\n  echo \"Type errors detected.\"\nfi\n```\n\n### Process multiple files\n\n```bash copy\nfor file in src/api/*.ts; do\n  echo \"--- Reviewing $file ---\" | tee -a review-results.md\n  copilot -p \"Review $file for error handling issues\" -s --allow-all-tools | tee -a review-results.md\ndone\n```\n\n## Further reading\n\n* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)\n* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options)"}