> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Copilot CLI

> Use environment variables to connect GitHub Copilot CLI to GravitexAI GPT and Claude models

## 1. Overview

GitHub Copilot CLI is a terminal coding Agent for interactive questions, code changes, planning, and autonomous execution. **BYOK** connects it to GravitexAI GPT or Claude models.

> [!NOTE]
>
> These settings target **CLI 1.0.9x**, with **1.0.98 (October 2026)** as the reference. Once `COPILOT_PROVIDER_BASE_URL` is set, the CLI calls your provider directly, without GitHub sign-in or a Copilot subscription.

## 2. Requirements

* macOS or Windows.
* **Node.js 22+** for npm installation.
* **PowerShell 6+** recommended on Windows.

## 3. Prerequisites

Create a key (`sk-xxxxxxxxxx`) in the [GravitexAI Console](https://maas.gravitex.ai/#/api-keys), confirm an available model ID, and make sure your computer can reach the API.

## 4. Connection settings

| Variable | GPT | Claude |
| - | - | - |
| `COPILOT_PROVIDER_TYPE` | `openai` | `anthropic` |
| `COPILOT_PROVIDER_BASE_URL` | `https://api.gravitex.ai/v1` | `https://api.gravitex.ai` (**no `/v1`**) |
| `COPILOT_PROVIDER_WIRE_API` | `responses` (`/v1/responses`) | Unset (`/v1/messages`) |
| `COPILOT_PROVIDER_API_KEY` | `sk-your-api-key` | The same key |
| `COPILOT_MODEL` | For example, `gpt-5.5` | For example, `claude-sonnet-5-5` |

> [!WARNING]
>
> GPT and Claude require different protocols. Claude does not support `/v1/responses`; use `anthropic` and the root Base URL. Only one set of provider variables is active per terminal. Switch both protocol and address when changing model families.

Common examples:

* GPT: `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-6-sol`.
* Claude: `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1`.

Use IDs available in your account and the [Model Catalog](https://maas.gravitex.ai/#/api-models), or query:

```bash theme={null}
curl -s https://api.gravitex.ai/v1/models -H "Authorization: Bearer sk-your-api-key"
```

## 5. Installation

### macOS

```bash theme={null}
# Option 1: Homebrew (recommended)
brew install --cask copilot-cli

# Option 2: npm (Node.js 22+ required)
npm install -g @github/copilot

# Option 3: official installer
curl -fsSL https://gh.io/copilot-install | bash
```

### Windows

```powershell theme={null}
# Option 1: WinGet (recommended; PowerShell 6+)
winget install GitHub.Copilot

# Option 2: npm (Node.js 22+ required)
npm install -g @github/copilot
```

You can also download an executable from [GitHub Copilot CLI Releases](https://github.com/github/copilot-cli/releases).

### Verify the installation

```bash theme={null}
copilot --version
# GitHub Copilot CLI 1.0.98.
```

## 6. Quick configuration for the current terminal

These settings expire when the terminal closes. Replace `sk-your-api-key`, then run one set matching your OS and model family.

> [tab] macOS (zsh / bash)
>
> **GPT**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=openai
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> export COPILOT_PROVIDER_API_KEY=sk-your-api-key
> export COPILOT_PROVIDER_WIRE_API=responses
> export COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> **Claude**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=anthropic
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> export COPILOT_PROVIDER_API_KEY=sk-your-api-key
> unset COPILOT_PROVIDER_WIRE_API
> export COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

> [tab] Windows PowerShell
>
> **GPT**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "openai"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
> $env:COPILOT_PROVIDER_API_KEY = "sk-your-api-key"
> $env:COPILOT_PROVIDER_WIRE_API = "responses"
> $env:COPILOT_MODEL = "gpt-5.5"
> copilot
> ```
>
> **Claude**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "anthropic"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
> $env:COPILOT_PROVIDER_API_KEY = "sk-your-api-key"
> Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
> $env:COPILOT_MODEL = "claude-sonnet-5-5"
> copilot
> ```

> [tab] Windows CMD
>
> ```bat theme={null}
> :: GPT
> set COPILOT_PROVIDER_TYPE=openai
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> set COPILOT_PROVIDER_API_KEY=sk-your-api-key
> set COPILOT_PROVIDER_WIRE_API=responses
> set COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> ```bat theme={null}
> :: Claude
> set COPILOT_PROVIDER_TYPE=anthropic
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> set COPILOT_PROVIDER_API_KEY=sk-your-api-key
> set COPILOT_PROVIDER_WIRE_API=
> set COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

## 7. Persistent configuration

BYOK providers are configured through environment variables, not `settings.json`. To persist them, put the variables in your shell configuration. Separate `copilot-gpt` and `copilot-claude` commands let you choose a family without entering every variable again.

### macOS: \~/.zshrc

```bash theme={null}
# Open the configuration file
open -e ~/.zshrc        # or vim ~/.zshrc
```

Append:

```bash theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
export GRAVITEX_API_KEY="sk-your-api-key"

# GPT: OpenAI protocol via /v1/responses
# Usage: copilot-gpt [model] [other copilot arguments...]
copilot-gpt() {
  local model="${1:-gpt-5.5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=openai \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1 \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_PROVIDER_WIRE_API=responses \
  COPILOT_MODEL="$model" \
  copilot "$@"
}

# Claude: Anthropic protocol via /v1/messages
# Usage: copilot-claude [model] [other copilot arguments...]
copilot-claude() {
  local model="${1:-claude-sonnet-5-5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=anthropic \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_MODEL="$model" \
  env -u COPILOT_PROVIDER_WIRE_API copilot "$@"
}
```

Reload and use:

```bash theme={null}
source ~/.zshrc
```

```bash theme={null}
copilot-gpt                         # Default: gpt-5.5
copilot-gpt gpt-5.3-codex           # Choose a model
copilot-claude                      # Default: claude-sonnet-5-5
copilot-claude claude-opus-5-5 --yolo   # Choose model + no-confirmation mode
```

> [!TIP]
>
> For one model family, you can persist the exports from section 6 and run `copilot` directly. Clear `COPILOT_PROVIDER_WIRE_API` when switching from GPT to Claude.

### Windows: PowerShell Profile

```powershell theme={null}
# Create the Profile if missing, then open it in Notepad
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -ItemType File -Force }
notepad $PROFILE
```

Append:

```powershell theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
$env:GRAVITEX_API_KEY = "sk-your-api-key"

# GPT: OpenAI protocol via /v1/responses
# Usage: copilot-gpt [model] [other copilot arguments...]
function copilot-gpt {
    param([string]$Model = "gpt-5.5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "openai"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    $env:COPILOT_PROVIDER_WIRE_API = "responses"
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}

# Claude: Anthropic protocol via /v1/messages
# Usage: copilot-claude [model] [other copilot arguments...]
function copilot-claude {
    param([string]$Model = "claude-sonnet-5-5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "anthropic"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}
```

Reopen PowerShell or run `. $PROFILE`. Usage is the same as on macOS.

> [!NOTE]
>
> If Profile scripts are blocked, use the temporary settings from section 6. Configure script execution policy according to your computer's management requirements if you need Profile loading.

### Windows user variables for a single model family

```powershell theme={null}
# GPT example: reopen the terminal after saving
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_TYPE", "openai", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_BASE_URL", "https://api.gravitex.ai/v1", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_API_KEY", "sk-your-api-key", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_WIRE_API", "responses", "User")
[Environment]::SetEnvironmentVariable("COPILOT_MODEL", "gpt-5.5", "User")
```

Reopen the terminal after saving. To remove a variable, repeat its command with `$null` as the second argument.

## 8. No-confirmation mode and permissions

By default, read-only actions are automatically approved, while writes and commands prompt for confirmation. The following options change this behavior.

### 1. YOLO: no-confirmation mode for one launch

```bash theme={null}
copilot --yolo          # No-confirmation mode
copilot --allow-all     # Equivalent to --yolo
```

`--yolo` / `--allow-all` combine:

| Flag | Effect |
| - | - |
| `--allow-all-tools` | Approve tools, file writes, commands, and MCP without prompts |
| `--allow-all-paths` | Allow any path; default scope is the current directory and children |
| `--allow-all-urls` | Allow any URL |

YOLO controls approvals. For continued autonomous execution until the task finishes, also add **`--autopilot`**:

```bash theme={null}
copilot --yolo --autopilot
```

### 2. Change permissions inside a session

| Command | Effect |
| - | - |
| `/allow-all` | Grant all permissions for this session |
| `/permissions` | Switch manual, assisted, and allow-all modes |

### 3. Persist the default permission mode

```bash theme={null}
# Use allow-all permissions by default in new interactive sessions
copilot config defaultPermissionMode allow-all

# Optional: default to autopilot in new sessions
copilot config defaultMode autopilot
```

Stored in `~/.copilot/settings.json` (Windows: `%USERPROFILE%\.copilot\settings.json`), equivalent to:

```json theme={null}
{
  "defaultPermissionMode": "allow-all",
  "defaultMode": "autopilot"
}
```

Restore defaults:

```bash theme={null}
copilot config defaultPermissionMode manual
copilot config defaultMode interactive
```

### 4. Non-interactive scripts and CI

`-p` requires `--allow-all-tools` or `--yolo`:

```bash theme={null}
copilot -p "Add unit tests for main.go" --yolo -s
```

Alternatively set `COPILOT_ALLOW_ALL=true`. This also trusts the current directory and loads its plugins, MCP servers, and hooks.

> [!WARNING]
>
> With full approval, the Agent can modify/delete files and run commands without asking. Enable it only as needed in trusted Git-managed projects and review the changes.

## 9. Daily use

```bash theme={null}
# Interactive mode
copilot

# Ask once and exit (-s prints only the answer)
copilot -p "Explain the directory structure of this project" -s --allow-all-tools

# Override the model for this run (same protocol required)
copilot --model gpt-5.4

# Resume the most recent session
copilot --continue

# Plan mode: review the plan before execution
copilot --mode plan
```

| Session command | Effect |
| - | - |
| `/model` | Switch models |
| `/allow-all` | Grant all permissions |
| `/permissions` | Change permission mode |
| `/help` | List commands |

## 10. Verification and troubleshooting

### Verify the connection

```bash theme={null}
# Run after setting the environment variables in section 6
copilot -p "Reply with exactly: OK" -s --allow-all-tools
```

An `OK` response without authentication, protocol, or model errors confirms the request works. For the persistent wrappers, replace `copilot` in this test with `copilot-gpt gpt-5.5` or `copilot-claude claude-sonnet-5-5`.

> [accordion] Model 'claude-xxx' not found on provider ... (HTTP 404)
>
> Claude was configured as openai with responses. Switch to the anthropic type.

> [accordion] Claude returns 404 or /v1/v1/messages
>
> Remove /v1 from the Anthropic Base URL; use [https://api.gravitex.ai](https://api.gravitex.ai).

> [accordion] GPT returns 404
>
> Add /v1 to the OpenAI-compatible Base URL: [https://api.gravitex.ai/v1](https://api.gravitex.ai/v1).

> [accordion] 401 / Invalid API key
>
> Check the key, balance, and model permissions. You can query /v1/models with curl first.

> [accordion] The CLI still asks for GitHub sign-in
>
> COPILOT\_PROVIDER\_BASE\_URL did not take effect. Check with `echo $COPILOT_PROVIDER_BASE_URL`, or `$env:COPILOT_PROVIDER_BASE_URL` in PowerShell.

> [accordion] Changes to \~/.zshrc do not apply
>
> Run source \~/.zshrc or reopen the terminal.

### View available options

```bash theme={null}
copilot help providers     # BYOK setup help
copilot help environment   # Environment variables
copilot help permissions   # Permission help
copilot help config        # settings.json options
```

## 11. Resources

* [GitHub Copilot CLI](https://github.com/github/copilot-cli)
* [GravitexAI API keys](https://maas.gravitex.ai/#/api-keys)
* [GravitexAI models](https://maas.gravitex.ai/#/api-models)
* [GitHub Copilot App setup](https://docs.gravitex.ai/en/integrations/github-copilot-app.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.