Skip to content
opencode

opencode

a AI (coding) agent. for CLI, TUI, Web, and Desktop. This page focuses on headless / non-interactive usage without the TUI.

one-off prompts

basic usage

opencode run "explain this code"

pipe content

cat main.ts | opencode run "refactor this to use async/await" -

attach files

opencode run -f README.md -f src/main.ts "update the readme based on the code"

specify a model

opencode run -m anthropic/claude-sonnet-4 "write tests for utils.ts"

use a specific agent

opencode run --agent task "summarize the last 3 commits"

json output (for scripting)

streams newline-delimited JSON events:

opencode run --format json "what is 2+2?"

auto-approve permissions (dangerous!)

useful in CI or trusted scripts where you can’t interact with permission prompts:

opencode run --dangerously-skip-permissions "run npm test"

show thinking blocks

opencode run --thinking "solve this leetcode problem"

continue a previous session

opencode run --continue "and now add error handling"

or continue a specific session:

opencode run --session ses_xxx "what was the next step?"

fork a session before continuing:

opencode run --session ses_xxx --fork "try a different approach"

set a session title

opencode run --title "refactor auth" "clean up the login flow"

run in a specific directory

opencode run --dir ~/projects/api "check for outdated dependencies"

providers & auth

list providers

opencode providers list

log in to a provider

opencode providers login

log out

opencode providers logout

models

list available models

opencode models

list models for a specific provider

opencode models anthropic

show model costs & metadata

opencode models --verbose

refresh model cache

opencode models --refresh

sessions

list sessions

opencode session list

delete a session

opencode session delete ses_xxx

stats & export

show token usage and costs

opencode stats
opencode stats --days 7
opencode stats --models

export a session

opencode export ses_xxx > session.json

redact sensitive data:

opencode export ses_xxx --sanitize

headless server

useful for running opencode as a background service or connecting from another machine:

start server

opencode serve --port 4096

attach to a running server

opencode attach http://localhost:4096

run via remote server

opencode run --attach http://localhost:4096 "hello from the client"

debugging

show resolved config

opencode debug config

show paths

opencode debug paths

show startup timing

opencode debug startup

misc

upgrade

opencode upgrade

shell completions

opencode completion bash
opencode completion zsh
opencode completion fish

database tools

opencode db path
opencode db "SELECT * FROM messages LIMIT 5"

global flags

  • -h, --help — show help
  • -v, --version — show version
  • --print-logs — print logs to stderr
  • --log-level DEBUG|INFO|WARN|ERROR — set log level
  • --pure — run without external plugins
  • -m, --model provider/model — model to use
  • --prompt <string> — prompt to use
  • --agent <string> — agent to use