Skip to content

Use the otomo command line

otomo does from a terminal what staff do in the admin website, with the same roles (viewer < live_ops < admin). Every command explains itself: otomo --help, otomo config --help, otomo config releases publish --help.

Install

Build it from services/cli (Go 1.27):

cd services/cli
./build.sh          # dist/otomo-windows-amd64.exe, otomo-linux-amd64, otomo-darwin-arm64

Each file is a single program with nothing else to install; put it on your PATH as otomo (otomo.exe on Windows).

Tell it where your environments are

otomo envs add staging    --url https://admin.staging.example.com --kind staging --default
otomo envs add production --url https://admin.example.com         --kind production
otomo envs

The URL is the address of the admin website. kind matters: a production environment is never used unless you name it with --env production, and every change to it asks for confirmation. When one admin website relays several environments, add --relay-prefix /env/<name>. The list is kept in environments.json in your user config folder (%AppData%\otomo on Windows, ~/.config/otomo on Linux, ~/Library/Application Support/otomo on macOS). OTOMO_URL (with OTOMO_ENV and OTOMO_ENV_KIND, production when unset) defines one on the fly.

How relay_prefix maps onto the admin website's environment switcher: gateway_dev's environment registry (deploy/environments.example.yaml, GATEWAY_DEV_ENVIRONMENTS_FILE) names each remote environment, and the website reaches it at /env/<name>/admin-auth/... and /env/<name>/api/admin/.... A CLI environment with --url set to that website and --relay-prefix /env/<name> (the registry's name, not its label) sends exactly those paths. The local environment of that website has no prefix. Sign in once per environment: the remote environment has its own staff accounts, and the relay keeps its refresh cookie under its own name (__Host-otomo_refresh_<name>), which the CLI uses whenever the prefix is exactly /env/<name>. Where the remote is also reachable directly, either address works.

Sign in

otomo login --env staging      # email, password (hidden), then your authenticator code
otomo auth status --env staging

Only a person signs in this way, in their own terminal; the login is stored for your computer user only (credentials.json, readable by you alone: mode 0600 on Linux and macOS; on Windows the file's access list is narrowed to your user with icacls, which is best effort — the folder is already private to you by default). It refreshes itself until the session ends. For an agent or a script, mint a token instead: see Let an agent run otomo. The token is read from --token-file, then OTOMO_TOKEN_<ENV>, then OTOMO_TOKEN, then a service-account secret in OTOMO_SERVICE_SECRET_<ENV> or OTOMO_SERVICE_SECRET (the CLI exchanges it for short-lived tokens by itself), then the stored login.

Recipes

Ship a config change

otomo config draft patch economy --set '/prices/gold=120' --env staging
otomo config namespaces diff economy --env staging          # what the next version holds
otomo config versions create economy --message "Gold costs 120" --env staging
otomo config releases suggest --channel staging --env staging
otomo config releases publish --channel staging --env staging --dry-run
otomo config releases publish --channel staging --env staging

You never type version numbers: suggest (and publish) take every namespace whose newest version is not on the channel yet, and write the message for you. Name namespaces with --namespaces economy,announcements to ship only those. The selection is worked out here; when the server has Config's GET /api/admin/config/releases/suggest (the route the admin UI's release form uses), the CLI sends it that selection and takes its message, minimum client version, change list and warnings ("source": "server"), otherwise it writes a plainer message itself ("source": "local"). When it is tested, promote what is on staging to players:

otomo config releases promote --to live --env production --dry-run
otomo config releases promote --to live --env production          # asks you to type "production"

Publishing to live and promoting need admin. As live_ops, propose instead and an admin approves: otomo config proposals create --kind release --channel live --env production.

Turn maintenance on and wait until it applies

otomo ops maintenance set --mode warning --title "Maintenance at 10:00 UTC" \
  --message "About 30 minutes" --env production --dry-run
otomo ops maintenance set --mode hard --env production --yes --wait
otomo ops maintenance clear --env production --yes --wait

--dry-run shows which kinds of traffic would close. --wait returns only when every enforcer reports the change applied (otomo ops status shows the same). Other languages of the title and message are kept.

Roll back

otomo config releases history --channel live --env production
otomo config releases rollback --channel live --env production --dry-run
otomo config releases rollback --channel live --env production --yes

Without --to it goes back to the release before the current head. Nothing is deleted; publishing again moves forward.

Post an announcement

otomo announcements add spring-event --locale en --title "Spring event" \
  --body "Starts Friday" --published --starts-at 2026-11-13T00:00:00Z --env staging
otomo announcements add spring-event --locale ja --title "春イベント" --body "金曜から" --published --env staging
otomo config versions create announcements --message "Spring event" --env staging
otomo config releases publish --channel staging --namespaces announcements --env staging

Rows are checked before anything is sent (id and language format, lengths, end after start, no duplicate id + language). announcements schedule changes the times or publishes/unpublishes; announcements remove deletes rows from the draft.

Look things up

otomo players list --q alice --env production
otomo players timeline <player-id> --env production
otomo economy reconciliation --env production
otomo gameservers list --env production
otomo services status --env production
otomo audit query --source config --from 2026-11-01T00:00:00Z --env production
otomo patch channels --env production

For scripts and agents

  • --json prints exactly one JSON object per run: {"ok":true,"command":"config.releases.publish","env":{"name":"staging","kind":"staging",…},"result":{…}}, or on failure {"ok":false,…,"error":{"code","message","hint","exit_code","upstream"}}. The env object is in every answer, so you always see where it went.
  • Exit codes: 0 ok, 1 unexpected, 2 usage or invalid input, 3 authentication, 4 forbidden by role, 5 not found, 6 conflict (someone changed it first, or nothing to do), 7 environment unavailable, 8 refused by a safety rule (production without --env, no confirmation, writes disabled).
  • otomo explain <code> explains an error code and what to do next.
  • otomo schema prints every command's input and output JSON Schema, the role it needs and whether it writes, is destructive or idempotent; otomo schema config releases publish prints one.
  • --dry-run reads what it needs and reports would_send without changing anything.
  • --yes confirms destructive and production writes without a prompt. Without a terminal and without --yes they are refused (exit 8), never silently done.
  • --input-json '{"channel":"staging"}' (or @file.json) passes all inputs at once.
  • A long-running agent uses a service account: an admin creates it with a role, scopes and an expiry of at most 90 days, and the agent sets OTOMO_SERVICE_SECRET. It can be propose-only. See Let an agent run otomo.
  • otomo mcp --env <name> --http-service :8765 serves the MCP server to many callers over HTTP (the compose profile agent runs it behind the admin gateway); each caller sends its own service-account secret as the bearer.
  • otomo doctor --env <name> checks the address, the token, the role and the clock; read result.ok.