opencode-sync

A cross-platform CLI that sets up opencode for new and existing projects in one command:

1. Installs opencode if it's missing (macOS, Linux, and Windows).
2. Fetches your provider's model list from an OpenAI-compatible /models endpoint.
3. Creates opencode.json for new projects, or merges/updates it for existing ones — no secrets are stored in the file.

opencode-sync --api-key sk-xxxx --endpoint https://your-api.com/v1

Features

• Globally callable — run it from any project directory.
• Works for new and existing projects — creates or merges opencode.json.
• Generic — point it at any OpenAI-compatible API. Just provide the API key and endpoint; optionally customize the provider naming.
• Handles the opencode install for you:
  • macOS → official install script + source ~/.zshrc guidance
  • Linux → official install script
  • Windows → npm install -g opencode-ai
• No secrets in config — API keys are written as {env:OPENCODE_PROVIDER_API_KEY}.
• Env var support — skip typing flags every time with ~/.zshrc / ~/.bashrc / PowerShell setx.
• Zero non-essential dependencies — only commander; networking uses Node's built-in fetch.

Requirements

• Node.js 18+ (node --version)
• npm 9+ (npm --version)
• A terminal on macOS, Linux, or native Windows (PowerShell/cmd). For the best experience on Windows, consider using WSL.

Install

Clone the repo and link it globally (dev setup):

git clone <your-repo-url> opencode-sync
cd opencode-sync
npm install
npm link          # makes `opencode-sync` available everywhere

With the package published to npm:

npm install -g opencode-sync

Verify:

opencode-sync --help

Quick start

New project (no opencode config yet)

cd /path/to/new-project
opencode-sync --api-key sk-xxxx --endpoint https://your-api.com/v1

The CLI creates opencode.json and prints a summary of the synced models.

Existing project (already uses opencode)

cd /path/to/existing-project
opencode-sync --api-key sk-xxxx --endpoint https://your-api.com/v1

The CLI detects the existing opencode.json, merges your provider entry and refreshes the model list, preserving the rest of the config.

Then

opencode

and select a model with /models.

Options

| Option | Description | Default / Env var | |---|---|---| | --api-key <key> | Provider API key. Written to the config as {env:OPENCODE_PROVIDER_API_KEY}. | OPENCODE_PROVIDER_API_KEY | | --endpoint <url> | Provider base URL, e.g. https://your-api.com/v1. | OPENCODE_BASE_URL | | --models-url <url> | Full models endpoint. Defaults to <endpoint>/models. | OPENCODE_MODELS_URL | | --provider-id <id> | Provider key in opencode.json. | provider-bambaw (OPENCODE_PROVIDER_ID) | | --provider-name <name> | Display name of the provider. | Bambaw (OPENCODE_PROVIDER_NAME) | | --dir <path> | Target project directory. | current directory | | --no-install | Skip the opencode install check (CI/testing). | — | | -h, --help | Show help. | — |

Naming conventions

Customize the provider id and display name to match your provider:

opencode-sync \
  --api-key sk-xxxx \
  --endpoint https://your-api.com/v1 \
  --provider-id provider-acme \
  --provider-name "Acme AI"

Resulting config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "provider-acme": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Acme AI",
      "options": {
        "baseURL": "https://your-api.com/v1",
        "apiKey": "{env:OPENCODE_PROVIDER_API_KEY}"
      },
      "models": { }
    }
  }
}

Env vars (avoid typing the api key)

macOS / Linux (~/.zshrc or ~/.bashrc):

export OPENCODE_PROVIDER_API_KEY="sk-xxxx"
export OPENCODE_BASE_URL="https://your-api.com/v1"
export OPENCODE_PROVIDER_ID="provider-bambaw"
export OPENCODE_PROVIDER_NAME="Bambaw Provider"

Windows (PowerShell):

setx OPENCODE_PROVIDER_API_KEY "sk-xxxx"
setx OPENCODE_BASE_URL "https://your-api.com/v1"

Then simply run:

opencode-sync

Non-standard models endpoints

opencode-sync --endpoint https://your-api.com/v1 \
  --models-url https://your-api.com/v1beta/your-org/models

Skip the install check

opencode-sync --endpoint https://your-api.com/v1 --no-install

How it works

opencode-sync --api-key <key> --endpoint <url> [--dir <path>]
        │
        ▼
1. opencode installed?  ──no──►  install it
        │               macOS/Linux: curl -fsSL https://opencode.ai/install | bash
        │ yes                  Windows:  npm install -g opencode-ai
        ▼                          │
        │                          ▼
        │                 macOS: source ~/.zshrc guidance
2. fetch GET <endpoint>/models  (with Bearer key if provided)
        │
        ▼
3. build config (convert models, merge into existing opencode.json if present)
        │
        ▼
4. write opencode.json   (created for new projects, merged for existing ones)

• Model entries are filtered to real models only (type === "model"), skipping image/audio/rerank entries returned by some APIs.
• limit.output is required by opencode and defaults to 65536 when the API omits it.
• Windows install targets the npm package so opencode lands in the same global bin as the CLI itself.

Development

npm link        # global command for local development
node bin/opencode-sync.js --help   # run without the link

Troubleshooting

| Problem | Fix | |---|---| | node: bad option / fetch is not a function | Node < 18. Update Node. | | ERROR: Missing --endpoint | Pass --endpoint or set OPENCODE_BASE_URL. | | HTTP 401 while fetching models | Wrong/expired API key, or the endpoint requires one — add --api-key. | | Invalid /v1/models response... | Not an OpenAI-style { "data": [...] } response — use --models-url for the exact endpoint. | | line 1: import: command not found | The #!/usr/bin/env node shebang is missing from bin/opencode-sync.js. | | opencode: command not found | macOS: source ~/.zshrc. Windows: reopen the terminal. | | command not found: opencode-sync | Re-run npm link inside the package folder. |

License

MIT