Spec-first development has one persistent leak: the moment your OpenAPI file and your published docs fall out of sync. You edit openapi.yaml, commit it, and then... someone has to remember to update the docs site. The new apikumo CLI (v0.3.0) closes that gap by making "publish my docs" a single terminal command you can wire into the same workflow that already tracks your spec.

It ships as a standalone binary — no Node.js runtime required — for macOS and Linux, with Windows on the way. Here's the full loop from install to a live, updated docs site.

Install

On macOS or Linux, the fastest path is Homebrew:

brew install apikumo/tap/apikumo
# later, to update:
brew upgrade apikumo

There's also a plain binary download if you'd rather not use a tap. Confirm it's on your PATH:

apikumo --version
# v0.3.0

Authenticate once

Login uses a device-code flow — the CLI prints a verification code and opens your browser to approve, so your password never touches the terminal. The token is stored in your system keychain (or ~/.apikumo/credentials) and can be revoked anytime from the dashboard.

apikumo login
# Press Enter to open browser… (use --no-prompt to skip this in scripts)

apikumo whoami
# email: you@example.com
# user_id: usr_…
# token_id: tok_…

whoami caches its result for an hour; pass --refresh to force a re-fetch from the server.

Bind a folder to a collection

apikumo init runs an interactive wizard: pick your org, workspace, and collection, then point it at the folder that holds your OpenAPI files. It writes a small .apikumo/config.json you commit alongside the spec.

apikumo init
# ? Select workspace › My Workspace
# ? Select collection › My API
# ✓ Config written to .apikumo/config.json

Now the repo knows which collection it publishes to — no flags to remember on every push.

Preview, then push

This is the part that makes it safe to automate. Run push with --dry-run first: it validates the spec and shows a diff of exactly what would change, persisting nothing.

apikumo push --dry-run
# validates openapi.yaml and prints the diff — no writes

Happy with the diff? Drop the flag and attach a note describing the change:

apikumo push --summary "Add pagination params to /orders"

Without --file, push discovers specs in your configured source folder and shows an interactive picker; point it at a single file when you want to be explicit:

apikumo push --file ./specs/orders.yaml --summary "Bump to v1.2"

Check state anytime with apikumo status, which prints your auth state, the bound collection ID, and the source folder with its file count.

Drop it into your workflow

Because every step is a flag-driven command, the natural move is a pre-push or CI check that validates the spec before it ever merges:

#!/usr/bin/env bash
# scripts/check-spec.sh — fail the build on an invalid or unexpected diff
set -euo pipefail
apikumo push --dry-run

Run that on pull requests to catch breaking spec changes early, then run a real apikumo push --summary "$GIT_COMMIT_MSG" on merge to main so your published docs are never more than one commit behind your spec.

A few housekeeping commands round it out: apikumo logout clears the stored token from the machine, and apikumo telemetry status|enable|disable controls the anonymous, no-personal-data usage counter.

Closing

A docs site that updates itself from the same OpenAPI file your code already depends on is the whole point of spec-first development — and a CLI is what turns that from a good intention into a one-line habit. If you want your terminal (and your CI) to keep your API docs honest, the APIKumo CLI gives you init, a --dry-run preview, and a single push that ships typed, searchable docs to your own subdomain. Grab the binary, run apikumo init, and let the spec be the source of truth.