Aperture CLI

The Aperture CLI configures and runs coding agents pre-connected to your Aperture proxy. It handles environment variables, configuration files, and provider type selection automatically, so you can start a coding session without editing configuration by hand.

Prerequisites

Before you use the Aperture CLI, confirm you have the following:

• A running Aperture proxy with at least one configured provider.
• Network access to the Aperture host URL. You can find your Aperture URL in the Aperture dashboard or at aperture.tailscale.com.
• At least one supported coding agent installed on your device. If you don't have one, the Aperture CLI provides install commands for each agent.
• Go version 1.26 or later installed on the device where you want to install aperture-cli.

Install the Aperture CLI

You can install the Aperture CLI using go install or by building it from the Aperture repository on GitHub. These instructions cover using go install.

1. Install the aperture-cli using go install:

   go install github.com/tailscale/aperture-cli/cmd/aperture@latest
   

2. Verify the installation by running the Aperture CLI:

   aperture
   

   The Aperture CLI displays a connection prompt or the main menu if a host is already configured. If you receive a command-not-found error, confirm that your Go bin directory is in your $PATH.

Connect to Aperture

The Aperture CLI connects to your Aperture proxy on startup and verifies your provider configuration.

1. Run the Aperture CLI:

   aperture
   

   If you have a saved endpoint in settings.json, the Aperture CLI connects to it automatically. If no endpoint is saved, the Aperture CLI prompts you to enter your Aperture URL. To change the host later, open the settings menu and add or select an endpoint under Aperture Endpoints.

2. Wait for the connection check to complete.

   The Aperture CLI queries the Aperture proxy for its list of configured providers and their API compatibility. If the host is unreachable, the Aperture CLI prompts you to enter a different URL.

3. After a successful connection, the Aperture CLI displays the main menu with your available coding agents.

   The Aperture CLI saves the connected host to your settings and uses it automatically on the next launch.

If the connection fails

When the Aperture CLI cannot reach your Aperture endpoint, it shows a setup guide instead of the main menu. The setup guide checks your Tailscale status and tells you what to do:

From the setup guide you can:

• Enter Aperture URL to point the Aperture CLI at a different Aperture instance.
• Retry connection to try the current endpoint again.
• Connection options to manage your list of endpoints.

Manage multiple endpoints

You can configure multiple Aperture proxy URLs and switch between them.

1. From the main menu, press s to open settings.

2. Select Aperture Endpoints.

3. Add or remove endpoints. Select an endpoint to make it the active host. The Aperture CLI uses the active endpoint on startup.

To delete an endpoint, highlight it and press d.

Launch a coding agent

After the Aperture CLI connects to Aperture, select a coding agent and provider type to start a coding session.

Select an agent

The main menu lists coding agents detected on your device. The Aperture CLI only shows agents that are installed on your device.

Connected to http://<aperture-hostname> (3 providers)

Which editor do you want to use?

  [0] Last Used: Claude Code - Google Vertex
  [1] Claude Code
  [2] OpenAI Codex
  [3] Gemini CLI
  [4] GitHub Copilot
  [5] OpenCode

  [i] Install agents
  [s] Settings
  [q] Quit

Selection (default: 0):

The [0] Last Used shortcut launches the same agent and provider type combination from your previous session. Press 0 or Enter to relaunch it.

If an agent you expect is missing from the list, the Aperture CLI couldn't find its binary. Refer to the troubleshooting section for resolution steps.

Select a provider type

After selecting an agent, choose a provider type. Provider types determine which API protocol the agent uses to reach AI models through the Aperture proxy. The Aperture CLI shows only provider types compatible with your configured providers.

Automatic selection

When a sub-menu contains only one option, the Aperture CLI selects it automatically and proceeds to the next step. If an agent supports only one compatible provider type, the Aperture CLI skips the provider type menu. If only one model is available, the Aperture CLI skips the model menu. This behavior applies only to sub-menus. The root menu always lists all installed agents regardless of how many provider types each supports.

What happens at launch

When you select an agent and provider type, the Aperture CLI:

1. Sets the environment variables the agent requires for the selected provider type. Some environment variable values include path suffixes (for example, /v1 or /bedrock) appended to the Aperture host URL.
2. Writes temporary configuration files if the agent requires them.
3. Appends skip-permissions flags if you've enabled YOLO mode (full-auto mode).
4. Saves your selection as the last-used combination.
5. Hands the full terminal to the coding agent.

When the agent exits, the Aperture CLI cleans up temporary files, re-checks the Aperture connection, and returns to the main menu.

Supported agents

The Aperture CLI supports six coding agents. Each agent declares which provider types it can use, and the Aperture CLI filters the list based on your Aperture configuration.

Claude Code

Claude Code is Anthropic's terminal coding agent for Claude models. For setup instructions, refer to use Claude Code with Aperture.

• Binary: claude
• Provider types: Anthropic API, AWS Bedrock, Google Vertex
• Install: curl -fsSL https://claude.ai/install.sh | bash
• Full-auto flag: --dangerously-skip-permissions

The Aperture CLI sets the following environment variables based on the selected provider type:

For the Google Vertex back end, the Aperture CLI sets CLOUD_ML_REGION and ANTHROPIC_VERTEX_PROJECT_ID to placeholder values (_aperture_auto_vertex_region_ and _aperture_auto_vertex_project_id_). The Aperture proxy resolves these values to the actual region and project ID at request time.

When you select a specific model, the Aperture CLI sets ANTHROPIC_MODEL with the provider prefix stripped (for example, anthropic/claude-sonnet-4 becomes claude-sonnet-4). This applies to the Anthropic API and Google Vertex back ends.

For the AWS Bedrock back end only, the Aperture CLI also sets model-tier variables (ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL) derived from the provider's model list by matching model names containing "opus", "sonnet", or "haiku". The Aperture CLI does not set these variables for the Anthropic API or Google Vertex back ends.

Gemini CLI

Gemini CLI is Google's terminal coding agent for Gemini models.

• Binary: gemini
• Provider types: Google Vertex, Gemini API
• Install: npm install -g @google/gemini-cli
• Full-auto flag: --yolo

The Aperture CLI sets the following environment variables based on the selected provider type:

For the Gemini API provider type, the Aperture CLI sets both GEMINI_BASE_URL and GOOGLE_GEMINI_BASE_URL for compatibility across Gemini CLI versions. Gemini CLI 0.40 or later reads GOOGLE_GEMINI_BASE_URL; earlier versions use GEMINI_BASE_URL.

The Aperture CLI sets GOOGLE_API_KEY and GEMINI_API_KEY to "not-needed". Gemini CLI requires these variables to be present, but Aperture handles authentication, so the values are not used.

The Aperture CLI also sets GEMINI_CLI_HOME to point to its managed configuration directory.

The Aperture CLI writes a persistent settings file at <config-dir>/aperture/gemini-home/.gemini/settings.json with the authentication type for the selected provider type. This file persists between sessions. Refer to persistent state for <config-dir> values by operating system.

GitHub Copilot

GitHub Copilot CLI is GitHub's terminal coding agent.

• Binary: copilot
• Provider types: OpenAI Compatible, Anthropic API
• Install: npm install -g @github/copilot

The Aperture CLI sets the following environment variables based on the selected back end:

GitHub Copilot supports two provider types (OpenAI Compatible and Anthropic API) with three back-end variants. The OpenAI Compatible provider type offers two wire-API modes: Chat Completions and Responses. The Aperture CLI presents all three back ends as options when a provider supports them.

GitHub Copilot does not support a full-auto mode flag.

OpenCode

OpenCode is a terminal coding agent that supports multiple AI providers. For setup instructions, refer to use OpenCode with Aperture.

• Binary: opencode
• Install: curl -fsSL https://opencode.ai/install | bash

Unlike the other agents, OpenCode does not use per-provider environment variables for routing. Instead, the Aperture CLI writes a temporary JSON configuration file to ~/.opencode/tmp_aperture_config.json and sets OPENCODE_CONFIG to point to it. The Aperture CLI deletes this file when the agent exits.

The Aperture CLI picks one of six AI SDK back ends automatically based on the provider's compatibility map:

For Amazon Bedrock providers, the Aperture CLI also sets placeholder environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION) since Aperture handles authentication upstream.

OpenCode does not support a full-auto mode flag. Model selection happens inside OpenCode itself.

OpenAI Codex

OpenAI Codex is OpenAI's terminal coding agent. For setup instructions, refer to use Codex with Aperture.

• Binary: codex
• Provider types: OpenAI Compatible
• Install: npm install -g @openai/codex
• Full-auto flag: --dangerously-bypass-approvals-and-sandbox

The Aperture CLI sets the following environment variables for Codex:

The Aperture CLI also sets CODEX_HOME to point to its managed configuration directory.

The Aperture CLI writes a persistent auth file at <config-dir>/aperture/codex-home/auth.json and a config.toml file in the same directory to prevent Codex from prompting for interactive login on first run. Refer to persistent state for <config-dir> values by operating system.

Claude Cowork

Claude Cowork is the desktop version of Claude, configured to route through the Aperture proxy. Unlike the CLI agents above, Cowork is a desktop application with no binary in $PATH, no environment variables, and no full-auto mode flag.

• Platform availability: macOS, Windows (not available on Linux)
• Install: The Aperture CLI opens the Claude download page in your browser. Install the app, then return to the Aperture CLI.
• Configuration: The Aperture CLI configures the Claude desktop app to use the Aperture proxy as its gateway.
  • On macOS, this uses defaults write to set the com.anthropic.claude domain.
  • On Windows, this writes to the HKCU\SOFTWARE\Policies\Claude registry key.
  • The Aperture CLI writes three settings: inferenceProvider=gateway, inferenceGatewayApiKey=-, and inferenceGatewayBaseUrl={url}.
• HTTPS requirement: Claude Cowork requires HTTPS for the gateway URL. The Aperture CLI automatically converts HTTP URLs to HTTPS. If your Aperture proxy uses a self-signed certificate, ensure your operating system trusts the certificate.
• No provider selection: Cowork always routes through the Aperture proxy's Anthropic API endpoint. The Aperture CLI does not offer back-end or model selection. Model selection happens inside the Claude desktop app.

Bridges

Bridges let you access Aperture through an embedded Tailscale node, so you do not need the Tailscale daemon (tailscaled) running on your machine.

When to use bridges

Use a bridge when:

• Your machine does not have Tailscale installed system-wide.
• You want to connect to Aperture from an environment where you cannot or prefer not to run the Tailscale daemon, such as a CI runner or a container. For an alternative that doesn't require the Aperture CLI, refer to connecting devices outside your tailnet.
• You want to use a separate Tailscale identity for Aperture access.

If you already have Tailscale running and connected, you do not need bridges. Direct endpoints work without any additional setup.

How bridges work

Each bridge is a lightweight, in-process Tailscale node (using tsnet). When you activate an endpoint that uses a bridge, the Aperture CLI:

1. Starts the embedded Tailscale node and connects it to your tailnet.
2. Creates a reverse proxy listening on localhost on a random available port.
3. Routes traffic from the local proxy through the Tailscale node to the remote Aperture endpoint.

The agent then connects to http://127.0.0.1:<port> instead of the remote URL. This is transparent to the agent.

Bridges persist their Tailscale state in <config-dir>/aperture/bridges/ (using the bridge ID), so they do not need to re-authenticate on every launch. Refer to persistent state for <config-dir> values by operating system.

Create a bridge

1. From the main menu, press s to open settings.
2. Select Bridges.
3. Press a to add a new bridge.
4. Enter a name for the bridge (for example, work or ci-runner).

The Aperture CLI generates a unique ID for the bridge and saves it to your settings.

Assign a bridge to an endpoint

After creating a bridge, connect it to an Aperture endpoint:

1. Go to Settings > Aperture Endpoints.
2. Press a to add a new endpoint.
3. Select Bridge (instead of Direct).
4. Choose the bridge you want to use.
5. Enter the Aperture URL (for example, https://ai.example.com).

The new endpoint appears in your endpoint list with the label https://ai.example.com via work.

Activate a bridge endpoint

Select a bridge endpoint from the Aperture Endpoints list. The Aperture CLI:

1. Shows a connecting status: Connecting bridge work to https://ai.example.com ...
2. Displays bridge connection logs as they arrive.
3. Runs the preflight check against the local proxy once connected.
4. Shows the main menu on success.

The first activation for a new bridge requires Tailscale authentication. Follow the URL printed in the bridge logs to authorize the node on your tailnet.

Delete a bridge

1. Go to Settings > Bridges.
2. Use the arrow keys to highlight the bridge you want to remove.
3. Press d to delete it.

You cannot delete a bridge that is still assigned to an endpoint. Remove or reassign the endpoint first.

Connection types

Configure settings

Press s from the main menu to open the settings screen.

Manage bridges

Add and remove embedded Tailscale nodes for connecting to Aperture without the system Tailscale daemon. For details on how bridges work and when to use them, refer to bridges.

1. Select Bridges from the settings menu.
2. Press a to add a new bridge and enter a name.
3. To delete a bridge, highlight it and press d.

Manage Aperture endpoints

Add and remove Aperture proxy URLs. The active endpoint is the host the Aperture CLI connects to on startup.

1. Select Aperture Endpoints from the settings menu.
2. Press a to add a new endpoint. Choose Direct to enter a URL directly, or Bridge to route through an embedded Tailscale node.
3. To switch to a different endpoint, select it from the list.
4. To delete an endpoint, highlight it and press d.

YOLO mode

YOLO mode appends skip-permissions flags when launching agents. When enabled, agents run without asking for confirmation before executing commands or making changes.

The following agents support YOLO mode flags:

OpenCode, GitHub Copilot, and Claude Cowork do not support YOLO mode flags.

To toggle YOLO mode:

1. Select YOLO mode from the settings menu.
2. Toggle the setting on or off.

The setting persists across sessions.

Install and uninstall agents

To install a coding agent:

1. Press i from the main menu, or select an agent marked as not installed.
2. The Aperture CLI displays the install command for the selected agent. Run the command in a separate terminal.
3. After installation, return to the Aperture CLI. The agent appears in the main menu on the next refresh.

To uninstall an agent:

1. Open settings and select Uninstall.
2. Select the agent to remove.
3. Confirm with y.

The uninstall action depends on the agent:

Keyboard shortcuts

The following keyboard shortcuts are available in the Aperture CLI:

Persistent state

The Aperture CLI stores settings and state in the OS default configuration directory under aperture/:

• macOS: ~/Library/Application Support/aperture/
• Linux: ~/.config/aperture/
• Windows: %LOCALAPPDATA%\aperture\

The Aperture CLI creates these files automatically on first use.

The settings.json file stores endpoints (with optional bridgeId references), bridge definitions, and the YOLO mode setting:

{
  "bridges": [
    {
      "id": "bridge-a1b2c3",
      "name": "work"
    }
  ],
  "endpoints": [
    {
      "url": "https://ai.example.com"
    },
    {
      "url": "https://ai-staging.example.com",
      "bridgeId": "bridge-a1b2c3"
    }
  ],
  "yoloMode": false
}

Troubleshoot the Aperture CLI

If the Aperture CLI doesn't behave as expected, check the following common issues. For general Aperture issues, refer to troubleshooting Aperture.

Aperture host unreachable

If the Aperture CLI can't connect to the Aperture host during the preflight check:

• Verify the Aperture proxy is running and accessible from your device.
• Confirm the host URL is correct.
• Check your network connection, firewall rules, and tailnet policy file rules.

The Aperture CLI prompts you to enter a different URL if the configured host is unreachable.

Agent binary not found

If a coding agent doesn't appear in the main menu:

• Verify the agent binary is installed by running which <binary-name> (for example, which claude).
• Confirm the binary is in your $PATH, or in one of the directories the Aperture CLI checks: ~/.local/bin, ~/bin, ~/.npm-global/bin, or ~/.opencode/bin/ (OpenCode only). The Aperture CLI finds binaries in system directories such as /usr/local/bin or /opt/homebrew/bin through your $PATH.
• Press i from the main menu to access install commands for each agent.

No compatible provider types available

If a coding agent appears but offers no provider type options:

• Verify that your Aperture proxy has providers configured with the API types the agent requires.
• Check the Aperture dashboard to confirm provider configuration.

Agent exits immediately

If a coding agent launches but exits immediately:

• Run the Aperture CLI with the -debug flag to display the environment variables the Aperture CLI sets before launch:

  aperture -debug
  

• Check the agent's own logs for error messages.

• Verify the Aperture proxy forwards requests correctly for the selected provider type.

Gemini CLI host validation fails

Gemini CLI 0.40 or later requires the Aperture host URL to use HTTPS and be a fully-qualified domain name (FQDN). If the Aperture CLI reports a host validation error when launching Gemini CLI:

• Confirm the Aperture endpoint uses https:// (not http://).
• Use a full domain name (for example, https://ai.example.com) rather than a short hostname like ai.
• Update the endpoint in Settings > Aperture Endpoints.

Gemini CLI's built-in validator rejects short hostnames and HTTP URLs. This requirement does not affect other agents.

Conflicting environment variables in Claude Code settings

If the Aperture CLI reports conflicting environment variables when launching Claude Code:

• Open ~/.claude/settings.json and check the env section.

• Remove any of the following variables that the Aperture CLI manages automatically:

  • ANTHROPIC_BASE_URL
  • ANTHROPIC_MODEL
  • ANTHROPIC_AUTH_TOKEN
  • ANTHROPIC_BEDROCK_BASE_URL
  • CLAUDE_CODE_USE_BEDROCK
  • CLAUDE_CODE_SKIP_BEDROCK_AUTH
  • CLOUD_ML_REGION
  • CLAUDE_CODE_USE_VERTEX
  • CLAUDE_CODE_SKIP_VERTEX_AUTH
  • ANTHROPIC_VERTEX_PROJECT_ID
  • ANTHROPIC_VERTEX_BASE_URL
  • ANTHROPIC_DEFAULT_OPUS_MODEL
  • ANTHROPIC_DEFAULT_SONNET_MODEL
  • ANTHROPIC_DEFAULT_HAIKU_MODEL
  • API_TIMEOUT_MS
  • ANTHROPIC_API_KEY

• The Aperture CLI sets these variables for you based on the selected provider type. This check is specific to Claude Code and its ~/.claude/settings.json file.

Bridge fails to connect

If the Aperture CLI shows a connecting status for a bridge endpoint and then fails:

• First-time auth required. The first time a bridge connects, it needs to authenticate with Tailscale. Look for a login URL in the bridge logs and open it in your browser.
• Bridge not authorized on your tailnet. Check that the bridge's node has been approved in your Tailscale admin console.
• Network issues. The embedded Tailscale node needs outbound internet access to reach the Tailscale coordination server.

Bridge cannot be deleted

If pressing d on a bridge shows an error that the bridge is in use by an endpoint:

• Go to Settings > Aperture Endpoints and delete or reassign the endpoint that references this bridge first, then delete the bridge.

Quick select not showing

If the main menu does not show the [0] quick select option even though you launched an agent before:

• The agent you last used was uninstalled.
• The provider you last used is no longer available from Aperture.
• The model you last used is no longer listed by the provider.
• The back end is no longer compatible with the provider.

The Aperture CLI only shows quick select when it can fully validate the previous launch state. Go through the normal selection flow to create a new launch record.

Command-line reference

The Aperture CLI accepts the following flags: