Skip to main content

Claude Code CLI

Claude Code uses the Anthropic Messages API shape. For router traffic, use the router base URL and a router-issued bearer token.

These docs are built into the hosted GenAI Smart Router server delivered for your deployment. Examples that show the router base URL use this browser origin, so on this deployment they render as https://your-router.example.com and https://your-router.example.com/v1.

For Claude Code deployment access, contact contact@metrum.ai.

Required Environment​

Use ANTHROPIC_AUTH_TOKEN for the router token. Keep ANTHROPIC_API_KEY reserved for direct Anthropic traffic; setting both for the router path can cause client warnings or incorrect authentication behavior.

Record the Claude Code version used for deployment validation with claude --version; CLI flags can change over time.

unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://your-router.example.com"
export ANTHROPIC_AUTH_TOKEN="rtr_metrum_<user>_<project>_<env>_<key>_<secret>"

One-Shot Check​

Use one of the model group IDs returned by /v1/models for --model. See Available Models And Access if you need to check which groups your token can request.

claude --bare --print --model "<allowed-model-group>" \
  "Reply with exactly: router claude ok"

Interactive Usage​

claude --model "<allowed-model-group>"

Use the same deployment-defined coding group for mixed coding and image tasks. Some hosted examples use big-coder as a coding-oriented group name; your deployment may use a different group name. When a Claude Code request includes image content, the router filters to multimodal Anthropic Messages-compatible targets inside that group; text-only and ordinary tool requests continue to use the normal coding targets.

Tool Smoke​

Run tool smokes inside a disposable container or equivalent isolated workspace because the command intentionally grants file and shell tools. Pass only the router base URL and a scoped router token into the sandbox, and mount only the scratch directory where the smoke file should be written.

mkdir -p "$PWD/claude-tool-smoke"
docker run --rm --network host --cap-drop ALL --security-opt no-new-privileges \
  --cpus 1 --memory 1g --pids-limit 256 --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=256m \
  --mount type=bind,source="$PWD/claude-tool-smoke",target=/workspace \
  -e "ANTHROPIC_BASE_URL={{origin}}" \
  -e "ANTHROPIC_AUTH_TOKEN=$ANTHROPIC_AUTH_TOKEN" \
  -w /workspace "$TOOL_SMOKE_IMAGE" \
  claude --bare --print --model "<allowed-model-group>" \
    --permission-mode bypassPermissions \
    --allowedTools "Write,Bash" \
    "Create claude_tool_smoke.txt containing exactly claude-tool-ok, run cat claude_tool_smoke.txt, then finish with claude-tool-ok."

The requested model must be allowed by the caller token. Deployment admins decide which model groups each key may use.

Image Input​

Claude Code sends image work through the Anthropic Messages API shape when an image is attached in the conversation. Use a deployment-defined router model group that is allowed for the caller token. The router filters image-bearing Messages requests to targets that advertise image in input_modalities.

For non-interactive validation, use the same Anthropic-compatible payload shape Claude Code sends:

curl "https://your-router.example.com/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "<allowed-model-group>",
  "max_tokens": 64,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "image", "source": {"type": "url", "url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}}
    ]
  }]
}'

Image-bearing Claude Code requests bypass router response caching. Usage records include image count and upstream cost fields when the upstream reports them.

For the full VLM routing configuration and equivalent OpenAI API examples, see Image Analysis And VLM Routing.

For the broader coding-agent validation matrix, including opencode, aider, and IDE/agent clients, see Coding-Agent Client Matrix.