Skip to main content
Version: v5.6.1

0.3 Your tools: contexts, output formats, the API, the docs

Included from Basic tier

After this you can: switch between servers with contexts, pick an output format, discover the API behind every command, open the embedded documentation from the CLI or the browser, and start the Academy for verified progress.

Before you start — tick each one:

  • Lesson 0.1 — Install and sign in (opschain learn 0.1)

In the GUI: the Docs area (/docs/<slug>) serves the same embedded pages opschain docs prints, deep-linked by slug.

Five tools ride along with every later lesson: contexts to point at the right server, output formats for scripts, the self-describing API, the embedded documentation, and the Academy. This lesson is a short tour of each, so none of them surprises you later.

1. Contexts​

Contexts let you hop between servers (and back to local mode) without retyping URLs:

opschain context list
NAME           SERVER                       ACTIVE
local          (local mode)
opschain-dev   http://127.0.0.1:8443        *
opschain context use local          # back to local mode
opschain context use opschain-dev
opschain context show               # the active target
Context: opschain-dev
Server: http://127.0.0.1:8443

opschain login records a context named after the server host (--context <name> to choose the name); lesson 0.2 explains how the active context decides a command's lane.

2. Output formats​

Every command renders a human table by default and takes -o table|json|yaml globally. The JSON shapes are stable contracts — build your scripts on them:

opschain whoami -o json
{
  "identity": {
    "username": "admin",
    "user_id": "01a1ae7e-828b-77ba-9c27-e2933055237b",
    "auth_provider": "local",
    "superuser": true
  },
  "server": "http://127.0.0.1:8443"
}

-o yaml renders exactly the same value as YAML. -q/--quiet trims progress output down to identifiers and errors — useful in scripts.

3. Discover the API​

The CLI is a client of the server's HTTP API, and the API describes itself. Print the full OpenAPI document, or just browse the route table:

opschain api spec                      # the targeted server's document
opschain api spec --local              # the copy embedded in this binary
opschain api routes --contains workflow_runs
METHOD  PATH                               AUTH  SUMMARY
GET     /api/workflow_runs                 user  List workflow runs.
POST    /api/workflow_runs                 user  Create a workflow run — the body's inputs object supplies the version's declared typed inputs, validated before the run exists.
DELETE  /api/workflow_runs/{id}            user  Cancel a workflow run.
GET     /api/workflow_runs/{id}            user  Show one workflow run.

Anything the CLI can do, your integrations can do over these routes — the AUTH column tells you which credential each endpoint wants.

4. Docs, from the CLI or the browser​

The documentation is embedded in the binary — the reference tree and these lessons — so it always matches the version you are running:

opschain docs                      # the index
opschain docs storage              # one reference page, by slug
opschain docs search "local mode"  # full-text search
opschain learn                     # the learning path
opschain learn 1.1                 # one lesson, by id

The server serves the same pages in the browser. Every page deep-links by its slug: /docs/storage, /docs/getting-started/1-1-projects-environments-assets-and-hosts; /docs/api-v2 is the interactive API reference. Client-side routes survive reloads and are shareable — the server serves the GUI for any unknown path, so a pasted /docs/... URL lands exactly where it says.

5. The Academy: verified progress​

Reading these lessons is free-form; the OpsChain Academy is the verified version. Its agent serves the learning path from a server of your own, decides whether an exercise was done by reading that server's state and audit events — never a quiz answer — and seals the result as signed, metadata-only evidence for the Academy Server that issues the badge. The agent never writes to OpsChain; you do the work exactly as in production.

Want verified progress? Install the pinned agent release and start it beside the server you are logged in to:

opschain academy install
opschain academy serve --single-learner --academy-server https://academy.limepoint.com --grant-file ~/academy-grant

Then open http://127.0.0.1:8070/, enrol, and start the first exercise — first-contact, which checks the login lesson 0.1 just made. The verified mode needs the packs:academy entitlement, which the Basic tier carries; a server whose licence lacks it is served no path, and the prose of these lessons stays readable regardless. The registration grant is issued by LimePoint for your organisation. opschain docs packs-academy describes the pack and its evidence model; opschain docs cli/academy is the command manual.

Check yourself​

  • Which flag turns any listing into JSON, and which command prints the route a CLI verb calls?

What you learned​

  • opschain context list|use|show switch between servers and local mode; login records a context for you.
  • -o json|yaml is a stable contract on every command; -q trims output for scripts.
  • opschain api spec and api routes expose the API every command calls.
  • opschain docs <slug> and opschain learn <id> are the embedded documentation, served at /docs/<slug> in the browser.
  • opschain academy install and academy serve start the verified mode, gated by packs:academy.

Next: this closes the module Start here — back to your track (opschain learn).