# GitHub Copilot CLI

The GitHub Copilot CLI is GitHub's terminal agent. It can send its model requests to a provider that you choose. These steps make the exchange that provider.

Copilot reads the settings from environment variables, so they apply only to the shell that you start it from.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts the Copilot CLI with the exchange as its provider. It sets the variables below for that process only.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login --browser --keys
liquid keys create laptop --save
liquid copilot
```

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- A model that supports tool calls and streaming. Copilot refuses a model without them.

## 1. Install the Copilot CLI

```bash
npm install -g @github/copilot
```

## 2. Point it at the exchange

Replace the placeholder with your buyer key. Use the same shell for each command below.

```bash
export LIQUID_API_KEY=sk-liquid-...
export COPILOT_MODEL=liquid.auto
export COPILOT_PROVIDER_API_KEY=$LIQUID_API_KEY
export COPILOT_PROVIDER_BASE_URL=https://router.inference.ai.exchange/v1
export COPILOT_PROVIDER_HEADERS="X-Title: GitHub Copilot CLI\nx-liquid-cap-usd: 1.00"
export COPILOT_PROVIDER_MAX_OUTPUT_TOKENS=16384
```

| Setting                              | Purpose                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `LIQUID_API_KEY`                     | Your buyer key.                                                                       |
| `COPILOT_PROVIDER_BASE_URL`          | The exchange URL, with `/v1`. Copilot sends Chat Completions requests.                |
| `COPILOT_PROVIDER_API_KEY`           | The key that Copilot sends as a bearer token.                                         |
| `COPILOT_MODEL`                      | The model for each request.                                                           |
| `COPILOT_PROVIDER_HEADERS`           | Headers for each request, separated by `\n`. See [Request headers](#request-headers). |
| `COPILOT_PROVIDER_MAX_OUTPUT_TOKENS` | The output limit of each request. Without it, Copilot sends no limit.                 |

Copilot needs no GitHub sign-in to use this provider. To stop it from contacting GitHub at all, also set `COPILOT_OFFLINE=true`.

## 3. Check it works

```bash
copilot -p "Reply with the word ready"
```

The answer must contain `ready`. Open **Credits → Receipts** to check the charge and the Copilot CLI client label.

## 4. Start a session

```bash
copilot
```

## Request headers

`COPILOT_PROVIDER_HEADERS` sends these headers with each model request, and
only to the exchange:

| Header             | Value                | Purpose                                    |
| ------------------ | -------------------- | ------------------------------------------ |
| `X-Title`          | `GitHub Copilot CLI` | Identifies the Copilot CLI on the receipt. |
| `x-liquid-cap-usd` | `1.00`               | Limits the charge for each request.        |

Keep the `X-Title` header. Without it, the receipt shows the OpenAI SDK as the
client.

## Control the cost

To set a different cap, change the value of `x-liquid-cap-usd` in `COPILOT_PROVIDER_HEADERS`. With `liquid copilot`, use `--cap`.

A task can cause several requests, and the request cap does not limit the total charge. Set a spend limit on the key to limit total spend. See [API keys](https://inference.ai.exchange/docs/keys.md).

Use a preset for other purchasing rules. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Refusals

A refused request costs nothing. The Copilot CLI handles each refusal as follows:

| Response     | What the Copilot CLI does                      |
| ------------ | ---------------------------------------------- |
| `400`, `402` | Shows the error at once.                       |
| `429`        | Tries 6 times in about a minute, then stops.   |
| `503`        | Tries 6 times in about 20 seconds, then stops. |

After you add funds or raise a spend limit, the next request works.

## Sampling parameters

Copilot sends `temperature`, `top_p`, `frequency_penalty` and `presence_penalty` with each request. The exchange sends the request only to an offer that accepts `top_p` and both penalties.

Most offers accept them. If none of the offers for your model do, the exchange refuses the request and makes no charge. See [Errors](https://inference.ai.exchange/docs/errors.md).

## Troubleshooting

| Symptom                              | Cause and fix                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
| `401`                                | Check that `COPILOT_PROVIDER_API_KEY` holds a valid key that has not expired.             |
| `402`                                | Add credit to the workspace or raise the key's spend limit.                               |
| `404`                                | Keep `/v1` at the end of `COPILOT_PROVIDER_BASE_URL`.                                     |
| The error names `no_eligible_offer`. | Read `eligibility.excluded` in the error. It names the rule that each offer did not meet. |

See [Errors](https://inference.ai.exchange/docs/errors.md) for the exchange's error codes and causes.

## Next steps

- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [API keys](https://inference.ai.exchange/docs/keys.md): key scope and spend limits.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): presets and caps.