Catwalk Documentation

The zai provider requires manual data extraction because specific parameters are not available via standard overview pages.

To update zai:

1. Retrieve the model list and capabilities from https://docs.z.ai/guides/overview/overview.
2. For context_window and default_max_tokens, do not use the overview page. Instead, extract the exact values from ./internal/providers/configs/openrouter.json.

To extend Catwalk with a new provider, follow these steps:

1. Create a new entry point at ./cmd/{provider-name}/main.go.
2. Determine the available models. You should attempt to use the provider's API to list models. If no API endpoint exists, look for structured text formats in their documentation.
3. Constraint: If you cannot programmatically determine the models, do not create a command. Instead, add the provider to the MANUAL_UPDATES.md file.
4. Register the new command in the GitHub Actions workflow at .github/workflows/update.yml to ensure it is included in automated updates.

You can use the following Go commands to interact with the Catwalk project:

• Start the HTTP server: Runs the main server on port :8080.
• Run a provider CLI: Builds and runs a specific CLI tool to update a provider's JSON file (e.g., go run ./cmd/openai).
• Run tests: Executes all tests in the repository.

go run .
go run ./cmd/{provider-name}
go test ./...

The avian command-line tool fetches the latest models from the Avian API (https://api.avian.io/v1/models) and generates a provider configuration file compatible with catwalk.

This tool automates the creation of internal/providers/configs/avian.json, mapping Avian's specific pricing and reasoning capabilities to the catwalk.Provider and catwalk.Model types. It specifically handles:

• Mapping reasoning capabilities to reasoning_levels (low, medium, high).
• Sorting models by name and then by ID.
• Setting the provider type to OpenAICompat.
• Configuring default large and small model IDs.

The synthetic command-line tool fetches available models from the Synthetic API and generates a synthetic.json configuration file for use within Catwalk.

Filtering Logic applied during generation:

• Models must have a ContextLength of at least 20,000.
• Models must support both text input and text output modalities.
• Models must support tools.

Configuration Details:

• The generated file is saved to internal/providers/configs/synthetic.json.
• The provider uses the OpenAICompat type.
• The API endpoint is https://api.synthetic.new/openai/v1.
• The API key is expected to be provided via the SYNTHETIC_API_KEY environment variable.

You can create a new Client instance using New() or NewWithURL(url string).

• New(): Automatically uses the CATWALK_URL environment variable. If that variable is not set, it defaults to http://localhost:8080.
• NewWithURL(url): Allows you to specify a custom base URL for the service. The client includes a default HTTP timeout of 30 seconds.

import "github.com/charmbracelet/catwalk"

// Using environment variables or default localhost:8080
client := catwalk.New()

// Using a specific URL
client, err := catwalk.NewWithURL("https://api.example.com")

The opencode-go command fetches the latest model definitions from https://models.dev/api.json, processes the pricing and reasoning capabilities, and generates a provider configuration file.

This tool is used to keep the opencode-go.json configuration in sync with the upstream model definitions. It automatically handles:

• Rounding costs to two decimal places.
• Mapping reasoning levels (e.g., low, medium, high) based on the model ID.
• Sorting models by name and then by ID.

The resulting configuration is written to internal/providers/configs/opencode-go.json with 0600 permissions.

The ionet command-line tool fetches available models from the io.net API and generates a provider configuration file (ionet.json) used by Catwalk.

It performs the following tasks:

1. Fetches models from https://api.intelligence.io.solutions/api/v1/models.
2. Filters models based on suitability for coding (e.g., prioritizing deepseek-r1, llama-3.2, mistral-nemo).
3. Calculates costs per 1M tokens from per-token prices.
4. Detects reasoning capabilities and reasoning levels (e.g., for gpt-oss).
5. Writes the resulting configuration to internal/providers/configs/ionet.json.

Note: The tool expects the IONET_API_KEY environment variable to be available for the provider configuration.