Skip to main content

Command Palette

Search for a command to run...

Headless / CI

GitHub Actions

Use Cursor CLI in GitHub Actions and other CI/CD systems to automate development tasks.

GitHub Actions integration

Basic setup:

- name: Install Cursor CLI  run: |    curl https://cursor.com/install -fsS | bash    echo "$HOME/.cursor/bin" >> $GITHUB_PATH- name: Run Cursor Agent  env:    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}  run: |    agent -p "Your prompt here" --model gpt-5

Cookbook examples

See our cookbook examples for practical workflows: updating documentation and fixing CI issues.

Other CI systems

Use Cursor CLI in any CI/CD system with:

  • Shell script execution (bash, zsh, etc.)
  • Environment variables for API key configuration
  • Internet connectivity to reach Cursor's API

Autonomy levels

Choose your agent's autonomy level:

Full autonomy approach

Give the agent complete control over git operations, API calls, and external interactions. Simpler setup, requires more trust.

Example: In our Update Documentation cookbook, the first workflow lets the agent:

  • Analyze PR changes
  • Create and manage git branches
  • Commit and push changes
  • Post comments on pull requests
  • Handle all error scenarios
- name: Update docs (full autonomy)  run: |    agent -p "You have full access to git, GitHub CLI, and PR operations.     Handle the entire docs update workflow including commits, pushes, and PR comments."

Restricted autonomy approach

Limit agent operations while handling critical steps in separate workflow steps. Better control and predictability.

Example: The second workflow in the same cookbook restricts the agent to only file modifications:

- name: Generate docs updates (restricted)  run: |    agent -p "IMPORTANT: Do NOT create branches, commit, push, or post PR comments.     Only modify files in the working directory. A later workflow step handles publishing."- name: Publish docs branch (deterministic)  run: |    # Deterministic git operations handled by CI    git checkout -B "docs/${{ github.head_ref }}"    git add -A    git commit -m "docs: update for PR"    git push origin "docs/${{ github.head_ref }}"- name: Post PR comment (deterministic)  run: |    # Deterministic PR commenting handled by CI    gh pr comment ${{ github.event.pull_request.number }} --body "Docs updated"

Permission-based restrictions

Use permission configurations to enforce restrictions at the CLI level:

{  "permissions": {    "allow": [      "Read(**/*.md)",      "Write(docs/**/*)",      "Shell(grep)",      "Shell(find)"    ],    "deny": ["Shell(git)", "Shell(gh)", "Write(.env*)", "Write(package.json)"]  }}

Authentication

Generate your API key

First, generate an API key from your Cursor dashboard.

Configure repository secrets

Store your Cursor API key securely in your repository using the GitHub CLI:

# Repository secretgh secret set CURSOR_API_KEY --repo OWNER/REPO --body "$CURSOR_API_KEY"# Organization secret (all repos)gh secret set CURSOR_API_KEY --org ORG --visibility all --body "$CURSOR_API_KEY"

Alternatively, use the GitHub UI: Go to your repository → Settings → Secrets and variables → Actions → New repository secret

Use in workflows

Set your CURSOR_API_KEY environment variable:

env:  CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}