Running GitHub Copilot CLI programmatically

Use Copilot CLI in the terminal, in scripts, or in Actions workflows.

In this article

Introduction

You 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.

To use Copilot CLI programmatically you can do either of the following.

  • Use the copilot command with the -p or --prompt command-line option, followed by your prompt:

    Shell
    copilot -p "Explain this file: ./complex.ts"

  • Pipe a prompt to the copilot command:

    Shell
    echo "Explain this file: ./complex.ts" | copilot

    Note

    Piped input is ignored if you also provide a prompt with the -p or --prompt option.

Tips for using Copilot CLI programmatically

  • 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.
  • Quote prompts carefully — use single quotes around your prompt if you want to avoid shell interpretation of special characters.
  • 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.
  • Use -s (silent) when capturing output. This suppresses session metadata so you get clean text.
  • Use --no-ask-user to prevent the agent from attempting to ask clarifying questions.
  • Set a model explicitly with --model for consistent behavior across environments.

See GitHub Copilot CLI programmatic reference for options that are particularly useful when running Copilot CLI programmatically.

CI/CD integration

A common use case for running Copilot CLI programmatically is to include a CLI command in a CI/CD workflow step.

This extract from a GitHub Actions workflow shows a simple example of running a Copilot CLI command.

# Workflow step using Copilot CLI
- name: Generate test coverage report
  env:
    COPILOT_GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
  run: |
    copilot -p "Run the test suite and produce a coverage summary" \
      -s --allow-tool='shell(npm:*), write' --no-ask-user

For more information, see Automating tasks with Copilot CLI and GitHub Actions.

Examples of programmatic usage

Generate a commit message

Bash
copilot -p 'Write a commit message in plain text for the staged changes' -s \
  --allow-tool='shell(git:*)'

Summarize a file

Bash
copilot -p 'Summarize what src/auth/login.ts does in no more than 100 words' -s

Write tests for a module

Bash
copilot -p 'Write unit tests for src/utils/validators.ts' \
  --allow-tool='write, shell(npm:*), shell(npx:*)'

Fix lint errors

Bash
copilot -p 'Fix all ESLint errors in this project' \
  --allow-tool='write, shell(npm:*), shell(npx:*), shell(git:*)'

Explain a diff

Bash
copilot -p 'Explain the changes in the latest commit on this branch and flag any potential issues' -s

Code review a branch

Use /review slash command to have the built-in code-review agent review the code changes on the current branch.

Bash
copilot -p '/review the changes on this branch compared to main. Focus on bugs and security issues.' \
  -s --allow-tool='shell(git:*)'

Generate documentation

Bash
copilot -p 'Generate JSDoc comments for all exported functions in src/api/' \
  --allow-tool=write

Export a session

Save the full session transcript to a Markdown file on the local filesystem.

Bash
copilot -p "Audit this project's dependencies for vulnerabilities" \
  --allow-tool='shell(npm:*), shell(npx:*)' \
  --share='./audit-report.md'

Save the session transcript to a gist on GitHub.com for easy sharing.

Bash
copilot -p 'Summarize the architecture of this project' --share-gist

Note

Gists are not available to Enterprise Managed Users, or if you use GitHub Enterprise Cloud with data residency (*.ghe.com).

Shell scripting patterns

Capture Copilot's output in a variable

Bash
result=$(copilot -p 'What version of Node.js does this project require? \
  Give the number only. No other text.' -s)
echo "Required Node version: $result"

Use in a conditional

Bash
if copilot -p 'Does this project have any TypeScript errors? Reply only YES or NO.' -s \
  | grep -qi "no"; then
  echo "No type errors found."
else
  echo "Type errors detected."
fi

Process multiple files

Bash
for file in src/api/*.ts; do
  echo "--- Reviewing $file ---" | tee -a review-results.md
  copilot -p "Review $file for error handling issues" -s --allow-all-tools | tee -a review-results.md
done

Further reading