opencode-switch

CLI and programmatic utilities for managing OpenCode providers, model mappings, and API key aliases.

opencode-switch keeps your real OpenCode provider configuration in sync while storing its own management metadata separately. It is useful when you want to:

• register multiple OpenCode-compatible vendors
• map stable model types such as gpt-5.4 and gemini to real upstream model IDs
• maintain multiple API keys per vendor/model pair
• switch the active vendor or active key without editing JSON files by hand

Features

• interactive shortcuts for common workflows
• explicit vendor, model, and key subcommands for scripting
• deterministic updates to OpenCode model and small_model pointers
• separate metadata storage for active vendor, managed models, and key aliases
• programmatic API exports for embedding the workflow in your own tools

Requirements

• Node.js >= 18.18.0
• An existing OpenCode setup, or permission to create files under ~/.config/opencode

Installation

Install globally:

npm install -g opencode-switch-cli

Or run without installing:

npx opencode-switch-cli vendor list

Files managed by the CLI

opencode-switch manages two files under ~/.config/opencode:

opencode.json

This is the real OpenCode config file. Providers are written under:

{
  "provider": {
    "duck": {
      "name": "duck",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://duck.example.com/v1",
        "apiKey": "duck-key"
      },
      "models": {
        "gpt-5.4": {
          "name": "duck/gpt-5.4"
        }
      }
    }
  },
  "model": "duck/gpt-5.4",
  "small_model": "duck/gemini"
}

opencode-switch.json

This file stores switch-specific metadata such as:

• active vendor
• managed providers
• managed model registry
• active key alias per model
• stored key aliases and credentials

Quick start

1. Add a vendor

opencode-switch vendor add duck \
  --npm @ai-sdk/openai-compatible \
  --base-url https://duck.example.com/v1 \
  --api-key duck-key

2. Add models for that vendor

Supported model types are currently:

• gpt-5.4
• gemini

opencode-switch model add duck gpt-5.4 --model duck/gpt-5.4
opencode-switch model add duck gemini --model google/gemini-2.5-flash

3. Add one or more key aliases

opencode-switch key add duck gpt-5.4 project-a --api-key duck-project-a-key
opencode-switch key add duck gpt-5.4 project-b --api-key duck-project-b-key

The first key added for a vendor + modelType becomes the active key by default.

4. Switch the active vendor

opencode-switch vendor use duck

This updates OpenCode pointers deterministically:

• model prefers vendor/gpt-5.4 when available
• small_model prefers vendor/gemini when available
• if the active primary model has an active key alias, the provider apiKey is updated too

Interactive shortcuts

These commands are useful for manual day-to-day operations:

opencode-switch ls
opencode-switch add duck https://duck.example.com/v1
opencode-switch rm
opencode-switch addk
opencode-switch switch
opencode-switch rmk

Shortcut behavior

• ls shows vendors in a dashboard-style list.
• add <name> <url> adds a vendor using the default npm package @ai-sdk/openai.
• rm opens an interactive vendor picker and confirmation step.
• addk walks through vendor -> model -> new key creation, and can create a missing model first.
• switch walks through vendor -> model -> existing key selection and activates the chosen key.
• rmk walks through vendor -> model -> key selection before deletion.

Command reference

Vendor commands

Add a vendor:

opencode-switch vendor add <vendorName> \
  --npm <npmPackage> \
  [--base-url <baseUrl>] \
  [--api-key <apiKey>]

Example:

opencode-switch vendor add duck \
  --npm @ai-sdk/openai-compatible \
  --base-url https://duck.example.com/v1 \
  --api-key duck-key

List vendors:

opencode-switch vendor list

Switch the active vendor:

opencode-switch vendor use duck

Remove a vendor:

opencode-switch vendor remove duck

Model commands

Add a model mapping:

opencode-switch model add <vendorName> <modelType> --model <realModel>

Examples:

opencode-switch model add duck gpt-5.4 --model duck/gpt-5.4
opencode-switch model add duck gemini --model google/gemini-2.5-flash

List models for a vendor:

opencode-switch model list duck

Remove a model mapping:

opencode-switch model remove duck gpt-5.4

Key commands

Add a key alias:

opencode-switch key add <vendorName> <modelType> <keyAlias> --api-key <apiKey> [--base-url <baseUrl>]

Example:

opencode-switch key add duck gpt-5.4 project-a --api-key duck-project-a-key

List keys for a vendor/model pair:

opencode-switch key list duck gpt-5.4

Switch the active key alias:

opencode-switch key use duck gpt-5.4 project-a

Remove a key alias:

opencode-switch key remove duck gpt-5.4 project-a

Behavior notes

• Unsupported model types are rejected. Right now only gpt-5.4 and gemini are valid.
• model list <vendorName> includes the active key alias when one is set.
• key use changes the active key only for the selected vendor + modelType pair.
• vendor use updates OpenCode's default pointers based on available managed models.
• Removing a vendor also removes its switch metadata and clears OpenCode pointers that referenced it.
• Existing provider options and model template metadata are preserved where possible.

Programmatic API

The package also exports reusable functions from dist/index.js / dist/index.mjs.

Exported functions

import {
  createJsonFileStore,
  createModelService,
  createOpencodeRepository,
  createSwitchRepository,
  createVendorService,
  executeCli,
  SUPPORTED_MODEL_TYPES,
} from 'opencode-switch-cli';

Example: create repositories and services

import os from 'node:os';
import path from 'node:path';

import {
  createJsonFileStore,
  createModelService,
  createOpencodeRepository,
  createSwitchRepository,
  createVendorService,
} from 'opencode-switch-cli';

const homeDir = os.homedir();
const configDir = path.join(homeDir, '.config', 'opencode');
const jsonStore = createJsonFileStore();

const opencodeRepository = createOpencodeRepository({
  filePath: path.join(configDir, 'opencode.json'),
  jsonStore,
});

const switchRepository = createSwitchRepository({
  filePath: path.join(configDir, 'opencode-switch.json'),
  jsonStore,
});

const vendorService = createVendorService({
  opencodeRepository,
  switchRepository,
});

const modelService = createModelService({
  opencodeRepository,
  switchRepository,
});

await vendorService.addVendor({
  vendorName: 'duck',
  npm: '@ai-sdk/openai-compatible',
  baseURL: 'https://duck.example.com/v1',
});

await modelService.addModel({
  vendorName: 'duck',
  modelType: 'gpt-5.4',
  realModel: 'duck/gpt-5.4',
});

Example: execute the CLI programmatically

import { executeCli } from 'opencode-switch-cli';

const result = await executeCli(['vendor', 'list']);

console.log(result.exitCode);
console.log(result.stdout);
console.error(result.stderr);

Local development

Install dependencies:

npm install

Run the CLI in development mode:

npm run dev -- vendor list

Run verification:

npm test
npm run typecheck
npm run build

Publishing to npm

The package is already configured with a prepublishOnly script:

npm run test && npm run typecheck && npm run build

When you are ready to release:

npm login
npm version patch
npm publish

If this is the first release for the package name, make sure the package name is available and that you are logged into the correct npm account before publishing.

License

MIT