Octri

CLI

Projects, specs and SDKs

Everything the dashboard does to a project, octri does from a terminal. This page covers the day-to-day: specs in, SDKs out, docs published.

Pick what you are working on

bash
octri projects list
octri projects use            # picker, or pass an id
octri auth whoami             # user, org, plan, selected project

The selected project is stored per profile. Override it for one command with --project <id>.

Specs

bash
octri specs push ./openapi.yaml
octri specs import https://example.com/openapi.json
octri specs list
octri specs status <specId>

specs push follows the whole pipeline, not just the upload. The spec parses in about a second; the doc pages, search index and changelog are written behind it, and the spinner names the stage it is on. Pass --no-wait to return as soon as the spec is accepted.

Reading a spec from stdin works, which is handy when you generate it:

bash
./scripts/build-spec | octri specs push -

octri specs status <specId> prints the same pipeline afterwards, one line per job, with the failure count if anything went wrong.

SDKs

bash
octri sdk languages                       # the catalogue and each language's options
octri sdk operations --grep checkout      # what the generator parsed
octri sdk validate                        # is this spec buildable
octri sdk audit                           # spec quality, scored

sdk audit is the one to run before a build. It scores the spec and lists what is costing you, marking which findings the generator can fix on its own:

bash
octri sdk audit
octri sdk audit apply <key>               # write the fix into the spec
octri sdk audit ignore <key>              # mute a finding you have decided about

Building:

bash
octri sdk preview --lang go               # real generator output, no build spent
octri sdk build --lang go,rust --download
octri sdk builds
octri sdk watch <buildId>
octri sdk download <buildId> --lang go --out ./sdk
octri sdk retry <buildId>                 # failed languages only

In a terminal, sdk build renders a lane per language and repaints it through generating, verifying, packaging, installing, ready. Piped or in CI it prints append-only lines instead. It exits non-zero if any language fails, so it works as a build step.

--detach returns as soon as the build is queued.

Settings and publishing

bash
octri sdk settings get --key reliability
octri sdk settings set retries.maxAttempts 5
octri sdk settings set --file settings.json

octri sdk repos                           # per-language GitHub targets
octri sdk publish <buildId> --mode pack   # dry run: build the package, don't push
octri sdk publish <buildId> --mode release
release is public and permanent

--mode release pushes to public package registries. Versions there cannot be taken back. Use --mode pack until you mean it.

Docs

bash
octri docs pages                          # generated pages
octri docs show <slug>
octri docs guides
octri docs nav
octri docs changelog

Regenerating:

bash
octri docs pages generate                 # only missing and stale pages
octri docs pages generate --all           # rebuild everything
octri docs pages regenerate <pageId>      # one page
octri docs pages publish <pageId>         # publish that page's draft
Your edits win, which is why a rebuild can look like it did nothing

Manual overrides sit on top of generated content. Rebuilding an edited page changes what is stored underneath and nothing of what a reader sees. --clear-overrides drops the edits as well, and asks for --yes first.

Versions and the public address:

bash
octri docs versions
octri docs versions publish <specId>
octri docs versions label <specId> "Stable"
octri docs versions default <specId>

octri docs domain set docs.example.com
octri docs domain                         # prints the CNAME and TXT to add
octri docs domain verify

Specs from GitHub

Point a project at a spec file in a repository and every push to it re-ingests:

bash
octri github connect acme/api --branch main --path openapi.yaml
octri github sync                         # pull it now
octri github auto-sync on
octri github status

Organisation

bash
octri orgs                                # orgs you belong to
octri orgs switch <id>
octri orgs usage
octri orgs billing
octri orgs members
octri orgs invites create dev@example.com --role member

orgs switch re-issues your session against the other organisation and clears the selected project, since projects do not cross organisations.

API keys

An API key is what a script or a service uses instead of your session.

bash
octri keys create "ci-pipeline"
octri keys list
octri keys revoke <keyId> --yes
The key is shown once

keys create prints the key a single time. There is no way to read it again. If you lose it, revoke it and make another.

Scripting it

--json prints one JSON document on stdout and nothing else. Errors go to stderr, and the exit code is non-zero on failure.

bash
octri sdk builds --json | jq '.[0].status'
octri monitoring issues --status unresolved --json | jq 'length'
Monitoring commands

Work production errors from the terminal.
CI setup

The pipeline pieces.