# How CLI Setup Scripts Configure Claude Code and Codex CLI with FreeLLMAPI

> Discover how FreeLLMAPI's CLI setup scripts configure Claude Code and Codex CLI. Learn how setup-claude and setup-codex commands inject BASE_URL and API_KEY for seamless integration.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-31

---

**FreeLLMAPI's unified CLI generates agent-specific configuration files through the `setup-claude` and `setup-codex` commands, invoking generator functions in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) to inject the correct BASE_URL and API_KEY values into Claude Code and Codex CLI config files.**

The tashfeenahmed/freellmapi repository ships a command-line interface that automates the integration of third-party coding agents with the FreeLLMAPI router. Understanding how these CLI setup scripts configure Claude Code and Codex CLI with FreeLLMAPI requires examining the tool definitions in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) and the generation context built from the server's model catalog.

## CLI Architecture and Tool Definitions

### The Metadata Registry in tools.ts

The configuration process is driven by a metadata table located in **[`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts)** at lines 605–610. This registry maps CLI commands to their respective generator implementations through structured entries:

```

['claude', 'Claude Code', …, 'setup-claude', …] → generator: claude(ctx)
['codex', 'Codex CLI', …, 'setup-codex', …]   → generator: codex(ctx)

```

Each entry associates the command name (e.g., `setup-claude`) with a specific generator function that accepts a context object. The `getTool()` function retrieves the appropriate definition from this table when a user executes a setup command.

## Step-by-Step Configuration Process

When you run `npx freellmapi setup-claude --url http://localhost:3001`, the CLI executes a six-stage pipeline defined in the entry point and tool modules:

1. **Parse CLI options** – The `commander` library in [`cli/src/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/index.ts) handles flags including `--url`, `--api-key`, `--profile`, and `--dry-run`

2. **Build generation context** – The CLI populates a `GenerateContext` object containing the router URL (e.g., `http://localhost:3001`), the unified API key, and available models fetched from the server's `/v1/models` endpoint using helper functions `v1Url` and `modelEntries`

3. **Select generator** – The system calls `getTool('claude')` or `getTool('codex')` to retrieve the tool definition from the metadata table

4. **Execute generator** – The function `claude(ctx)` or `codex(ctx)` returns a `Generation` object containing:
   - `files`: Configuration objects specifying target paths and JSON content
   - `notes`: Shell-style instructions for launching the agent

5. **Write with backup protection** – The CLI writes configuration files to their expected locations only after creating backups of existing files, ensuring no data loss

6. **Optional isolated launch** – The `launch-claude` or `launch-codex` commands spawn the agent with temporary environment variables, leaving the host shell unmodified

## Generating Claude Code Configuration

The `claude(ctx)` generator creates a JSON configuration at **`~/.config/claude/code/config.json`**. This file sets two critical environment variables:

- `BASE_URL`: Points to the FreeLLMAPI endpoint (e.g., `http://localhost:3001/v1`)
- `API_KEY`: Contains the unified FreeLLMAPI token

The generator also produces explanatory notes indicating that the `freellmapi launch` command will inject these credentials only for the child process, maintaining isolation from your global environment.

```bash

# Generate Claude Code configuration

npx freellmapi setup-claude --url http://localhost:3001

# Resulting ~/.config/claude/code/config.json contains:

# {

#   "BASE_URL": "http://localhost:3001/v1",

#   "API_KEY": "freellmapi-<token>"

# }

```

## Generating Codex CLI Configuration

For Codex CLI, the `codex(ctx)` generator produces **`~/.codex/config.json`** with OpenAI-compatible variable names:

- `OPENAI_BASE_URL`: Mapped to your FreeLLMAPI router URL
- `OPENAI_API_KEY`: Set to the FreeLLMAPI unified key

This alignment allows Codex CLI to communicate with the FreeLLMAPI server as if it were the standard OpenAI API, including a ready-to-run `curl` example in the output notes.

```bash

# Generate Codex CLI configuration

npx freellmapi setup-codex --url http://localhost:3001

# Resulting ~/.codex/config.json contains:

# {

#   "OPENAI_BASE_URL": "http://localhost:3001/v1",

#   "OPENAI_API_KEY": "freellmapi-<token>"

# }

```

## Safety Features and File Backup

The setup scripts implement defensive file operations to protect existing configurations. Before writing any new settings, the CLI creates backups of existing files at the target locations. According to the documentation in [`docs/clients.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/clients.md) (lines 29–40) and the [`README.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/README.md) (lines 137–140), the system **never overwrites existing custom settings** without first preserving the original state. This safety net ensures that running `setup-claude` or `setup-codex` is non-destructive to your existing development environment.

## Temporary Environment Launching

The `freellmapi launch` commands (e.g., `npx freellmapi launch-claude --url http://localhost:3001`) provide an ephemeral alternative to persistent configuration. Instead of writing files to disk, these commands:

- Generate the configuration in memory
- Spawn the agent process with the credentials injected as environment variables
- Remove the configuration when the process exits

This approach keeps your `~/.config` directories clean and prevents API keys from persisting on disk, which is ideal for shared workstations or temporary testing scenarios.

## Summary

- **Tool definitions in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts)** map `setup-claude` and `setup-codex` commands to their respective `claude(ctx)` and `codex(ctx)` generator functions
- **Generator functions** return `Generation` objects containing file paths and JSON content specific to each agent's expected configuration format
- **Configuration files** set `BASE_URL`/`OPENAI_BASE_URL` and `API_KEY`/`OPENAI_API_KEY` to route requests through the FreeLLMAPI server
- **Backup protection** ensures existing configurations are preserved before any modifications occur
- **Launch commands** create temporary environments that isolate credentials to a single child process

## Frequently Asked Questions

### What configuration files does FreeLLMAPI modify for Claude Code?

The CLI creates or updates **`~/.config/claude/code/config.json`** when running `setup-claude`. This JSON file contains the `BASE_URL` pointing to your FreeLLMAPI router endpoint and the `API_KEY` containing your unified authentication token. The generator function `claude(ctx)` in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) constructs this specific file structure expected by the Claude Code binary.

### How does the CLI prevent overwriting my existing agent configurations?

Before writing any new configuration, the scripts implemented in [`cli/src/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/index.ts) create backups of existing files at the target locations. As documented in the repository's README and client documentation, the system preserves original settings and never performs destructive overwrites. This allows you to run setup commands repeatedly or revert changes if needed.

### Can I use FreeLLMAPI with coding agents without saving API keys to disk?

Yes. The **`launch-claude`** and **`launch-codex`** commands generate configurations in memory and spawn the agent process with temporary environment variables. These credentials exist only for the duration of the child process and are not written to `~/.config/claude` or `~/.codex` directories, keeping your host environment completely clean.

### Where does the CLI store the mapping between setup commands and their generators?

The mapping is defined in **[`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts)** at lines 605–610, which contains a metadata table linking command names like `setup-claude` to their implementation functions. The `getTool()` function queries this registry to retrieve the correct generator (e.g., `claude` or `codex`) when processing a setup request.