UsageAtlasBeta
Sign inGitHubOpen source
OpenCode

How to use OpenCode: install, models, and usage

A practical OpenCode setup: install the CLI, authenticate a provider, choose a model, run a task, and find the usage data afterward.

By UsageAtlas on

Quick answer

Install OpenCode with the package manager or install script, run `opencode auth login` to connect a provider, start `opencode` in a project, and pick a model with `/models`. Usage is written to the local data folder automatically, so you can review tokens and cost after the session.

Install and connect a provider

npm i -g opencode-ai
# or
brew install sst/tap/opencode
opencode auth login

auth login lists providers and asks for the credential each one needs. Use an API key for metered billing or a subscription-backed provider where supported.

Run your first task

  1. Change into a project directory and run opencode.
  2. Open /models and choose a model. Start with a cheap one for exploration.
  3. Describe the task and point at specific files rather than the whole repo.
  4. Use /sessions to return to an earlier conversation.
  5. Run opencode run "prompt" for a one-shot, non-interactive task.

Find the usage afterward

Every assistant message records tokens and, where available, cost. The data lives in ~/.local/share/opencode on macOS and Linux and %APPDATA%\opencode on Windows.

  • Query the database for a total.
  • Use opencode stats where available.
  • Or open UsageAtlas for history and a model split.

A first week that produces usable data

The point of a first week is not to learn every flag. It is to produce sessions you can measure, so the second week starts with evidence rather than impressions.

  1. Configure one provider key and confirm a session completes.
  2. Do three real tasks rather than toy prompts.
  3. At the end of each day, check the token total.
  4. After a week, compare per-task cost across the three tasks.
  5. Add a second provider only after the first is measured.

The OpenCode usage guide covers where the numbers live, and OpenCode free models covers the zero-cost option.

Questions, answered

Do I need an API key to use OpenCode?

You need a provider credential. Some providers offer free models, and local models need no key.

Where is the OpenCode config file?

In ~/.config/opencode on macOS and Linux, and under %APPDATA%\opencode on Windows. The exact filename depends on the version.

Can I use OpenCode offline?

Only with a local model. Hosted providers need a network connection.

Browse by topic