# freellmapi

Point your coding agent at a [FreeLLMAPI](https://github.com/tashfeenahmed/freellmapi)
gateway in one command. The generators read the models your server is actually
serving and write the config file each tool expects.

```bash
npx freellmapi setup-claude --url http://localhost:3001 --api-key <your-key>
```

No install step, no account. The unified API key comes from your FreeLLMAPI
dashboard (or the tray popover in the desktop app).

## Commands

| Command | Tool |
| --- | --- |
| `setup-claude` | Claude Code |
| `setup-codex` | Codex CLI |
| `setup-cline` | Cline |
| `setup-continue` | Continue |
| `setup-aider` | Aider |
| `setup-opencode` | OpenCode |
| `setup-goose` | Goose |
| `setup-qwen` | Qwen Code |
| `setup-roo` | Roo Code |
| `setup-kilo` | Kilo Code |
| `setup-crush` | Crush |
| `setup-dsh` | DeepSeek Harness (`dsh`) |
| `setup-mimo` | MiMo Code (`mimo`) |
| `setup-atomcode` | AtomCode (`atomcode`) |
| `setup-openclaw` | OpenClaw |
| `setup-hermes` | Hermes Agent (`hermes`) |
| `setup-pi` | Pi (`pi`) |
| `setup-reasonix` | Reasonix (`reasonix`) |
| `setup-cursor` | Cursor |
| `setup-generic` | Any OpenAI-compatible client |
| `launch` | Run Claude Code with credentials injected into the child process |
| `launch-codex` | Run Codex the same way |
| `list` | Print the supported tools and their base URLs |
| `keys` | Add, list, remove, or test provider keys (`keys --help`) |

## Options

| Flag | Meaning |
| --- | --- |
| `--url URL` | Gateway base URL (default `http://localhost:3001`) |
| `--api-key KEY` | Unified API key |
| `--profile NAME` | Name the generated profile/provider entry |
| `--model ID` | Pin a specific model instead of the catalog default |
| `--dry-run` | Print the diff and write nothing |

`FREELLMAPI_URL` and `FREELLMAPI_API_KEY` work in place of `--url` / `--api-key`.

## Provider keys

The `keys` commands use a **dashboard session token**. Set
`FREELLMAPI_DASHBOARD_TOKEN`, or pass `--token TOKEN` to override it. This is the
session returned by dashboard sign-in (stored in the signed-in browser's local
storage as `freellmapi_dashboard_token`). The unified `--api-key` /
`FREELLMAPI_API_KEY` used by coding agents cannot authenticate these commands.
The CLI does not log in or persist the dashboard token.

```bash
export FREELLMAPI_URL=http://localhost:3001
export FREELLMAPI_DASHBOARD_TOKEN='<dashboard-session-token>'

npx freellmapi keys add groq                 # hidden provider-key prompt
npx freellmapi keys add groq --key '<key>'   # non-interactive alternative
npx freellmapi keys list
npx freellmapi keys test groq                # check every stored Groq key
npx freellmapi keys test groq --id 7         # check one key
npx freellmapi keys remove groq --id 7
```

`keys list` prints each key's ID, platform, enabled chat model count,
enabled/disabled state, and stored health status. Counts respect the key's model
scope; custom keys count models registered to their endpoint. Credentials and
masked keys are never printed. Use the IDs from this list when a platform has
multiple keys: `remove` requires `--id` in that case, and also checks that the ID
belongs to the requested platform. With one matching key, `--id` is optional.

`add` saves the key and immediately validates it through the gateway. A failed or
inconclusive check exits with code 1 and **leaves the key saved** for later testing
or removal. `test` also exits with code 1 if any selected key is not healthy or the
gateway cannot confirm its validity (for example, after a provider network
failure). Successful commands exit with code 0; argument, authentication, and
request errors exit with code 1. Validation uses the gateway's usual health
checks, including its policy of disabling a key after repeated confirmed failures.

Keyless providers skip the prompt. Custom endpoints need a URL and model
registration, so create them in the dashboard; existing custom keys can be
listed, tested, and removed here. Requests accept `--url` / `FREELLMAPI_URL` and
`--timeout MS` (30,000 ms per request by default). `--dry-run` is not supported for
`keys`; it is rejected before any request.

## Safety

Every generator is non-destructive: it merges into your existing configuration
rather than replacing it, and takes a timestamped backup before touching a file
that already exists. `--dry-run` shows the exact diff first.

The two `launch` commands never write credentials to disk at all — they inject
them into the child process environment for that run only.

## Requirements

Node.js >= 20.18. A running FreeLLMAPI gateway
([install guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md)).

## Links

- [Clients & coding agents guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md)
- [Issue tracker](https://github.com/tashfeenahmed/freellmapi/issues)

MIT © Tashfeen Ahmed