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

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 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 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 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 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.

# 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.

# 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 (lines 29–40) and the 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}