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. For more information, see About cloud and local sandboxes for GitHub Copilot.
  • Consider --assisted-approval when you can't predict in advance which tools a task will need. A model-based safety review can approve eligible permission requests without you granting blanket permissions. Existing permission rules still apply, and requests that still require your approval are denied in unattended runs. For more information, see GitHub Copilot CLI programmatic reference.
  • 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