198 lines
4.0 KiB
Markdown
198 lines
4.0 KiB
Markdown
---
|
|
summary: "Use GitHub Copilot CLI as a text-only fallback backend"
|
|
read_when:
|
|
- You want to use GitHub Copilot CLI as a model provider
|
|
- You need a fallback when API providers fail
|
|
- You already have GitHub Copilot CLI installed
|
|
---
|
|
# GitHub Copilot CLI
|
|
|
|
GitHub Copilot CLI (`copilot`) is GitHub's terminal-based AI assistant. Moltbot can use it as a
|
|
**CLI backend** for text-only fallback when API providers are unavailable.
|
|
|
|
## Prerequisites
|
|
|
|
- **GitHub account** (free tier works for `gpt-4.1`)
|
|
- **GitHub CLI** (`gh`) authenticated with your GitHub account
|
|
|
|
Note: `gpt-4.1` is available on the free GitHub tier. Other models like `gpt-4o`, `claude-sonnet-4-5`,
|
|
and `claude-opus-4-5` require a paid GitHub Copilot subscription.
|
|
|
|
## Installation
|
|
|
|
Install the Copilot CLI via npm:
|
|
|
|
```bash
|
|
npm install -g @github/copilot
|
|
```
|
|
|
|
Or via Homebrew:
|
|
|
|
```bash
|
|
brew install github/copilot/copilot
|
|
```
|
|
|
|
Or use the `gh copilot` extension:
|
|
|
|
```bash
|
|
gh extension install github/gh-copilot
|
|
```
|
|
|
|
Verify installation:
|
|
|
|
```bash
|
|
copilot --help
|
|
# or
|
|
gh copilot --help
|
|
```
|
|
|
|
## Quick start
|
|
|
|
Use Copilot CLI directly with Moltbot:
|
|
|
|
```bash
|
|
moltbot agent --message "hi" --model copilot-cli/gpt-4.1
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Minimal config (custom command path)
|
|
|
|
If your gateway runs under launchd/systemd with a minimal PATH, specify the full path:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
cliBackends: {
|
|
"copilot-cli": {
|
|
command: "/opt/homebrew/bin/copilot"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Using as a fallback
|
|
|
|
Add `copilot-cli` to your fallback list so it only runs when primary models fail:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
model: {
|
|
primary: "github-copilot/gpt-4.1",
|
|
fallbacks: [
|
|
"copilot-cli/gpt-4.1"
|
|
]
|
|
},
|
|
models: {
|
|
"github-copilot/gpt-4.1": { alias: "Copilot" },
|
|
"copilot-cli/gpt-4.1": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Supported models
|
|
|
|
Copilot CLI supports these models (availability depends on your GitHub plan):
|
|
|
|
**Free tier (GitHub Free):**
|
|
- `gpt-4.1` ← recommended default
|
|
- `gpt-4.1-mini`
|
|
|
|
**Paid tier (GitHub Copilot subscription):**
|
|
- `gpt-4o`
|
|
- `gpt-4-turbo`
|
|
- `claude-sonnet-4-5`
|
|
- `claude-opus-4-5`
|
|
|
|
Example model refs:
|
|
|
|
```
|
|
copilot-cli/gpt-4.1
|
|
copilot-cli/gpt-4.1-mini
|
|
copilot-cli/gpt-4o
|
|
copilot-cli/claude-sonnet-4-5
|
|
```
|
|
|
|
## Authentication
|
|
|
|
Copilot CLI uses GitHub CLI authentication. Ensure you're logged in:
|
|
|
|
```bash
|
|
gh auth status
|
|
```
|
|
|
|
If not logged in:
|
|
|
|
```bash
|
|
gh auth login
|
|
```
|
|
|
|
## Limitations
|
|
|
|
- **Text output only**: Copilot CLI does not support JSON output, so responses are plain text.
|
|
- **Tools disabled**: CLI backends never receive tool calls. The CLI may still run its own agent tooling internally.
|
|
- **No streaming**: CLI output is collected then returned.
|
|
- **Session resume**: Uses `--resume` flag with session ID when available.
|
|
|
|
## Differences from the API provider
|
|
|
|
| Aspect | `github-copilot` (API) | `copilot-cli` (CLI backend) |
|
|
|--------|------------------------|----------------------------|
|
|
| Output format | JSON (structured) | Text only |
|
|
| Tools | Moltbot tools work | Tools disabled |
|
|
| Streaming | Supported | Not supported |
|
|
| Auth | Device flow / token exchange | GitHub CLI (`gh auth`) |
|
|
|
|
Choose the API provider (`github-copilot`) for full functionality. Use `copilot-cli` as a
|
|
fallback when you want "always works" text responses.
|
|
|
|
## Troubleshooting
|
|
|
|
### CLI not found
|
|
|
|
Set the full command path in your config:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
cliBackends: {
|
|
"copilot-cli": {
|
|
command: "/usr/local/bin/copilot"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Authentication errors
|
|
|
|
Re-authenticate with GitHub CLI:
|
|
|
|
```bash
|
|
gh auth login
|
|
gh auth status
|
|
```
|
|
|
|
### Model not available
|
|
|
|
Model availability depends on your GitHub Copilot plan. Try a different model:
|
|
|
|
```bash
|
|
moltbot agent --message "hi" --model copilot-cli/gpt-4.1
|
|
```
|
|
|
|
## See also
|
|
|
|
- [GitHub Copilot (API provider)](/providers/github-copilot)
|
|
- [CLI backends](/gateway/cli-backends)
|
|
- [Configuration](/gateway/configuration)
|