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):
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¶
--jsonprints 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"}}. Theenvobject is in every answer, so you always see where it went.- Exit codes:
0ok,1unexpected,2usage or invalid input,3authentication,4forbidden by role,5not found,6conflict (someone changed it first, or nothing to do),7environment unavailable,8refused by a safety rule (production without--env, no confirmation, writes disabled). otomo explain <code>explains an error code and what to do next.otomo schemaprints every command's input and output JSON Schema, the role it needs and whether it writes, is destructive or idempotent;otomo schema config releases publishprints one.--dry-runreads what it needs and reportswould_sendwithout changing anything.--yesconfirms destructive and production writes without a prompt. Without a terminal and without--yesthey 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 :8765serves the MCP server to many callers over HTTP (the compose profileagentruns 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; readresult.ok.