okibi.ai

Command Palette

Search for a command to run...

Publish a Release and Install It with the Okibi CLI

Last updated: 11/18/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

Publish a Release and Install It with the Okibi CLI

Making a release official gives the CLI a signed install command for your workspace. Install access defaults to workspace members, and making it public is a separate command. Setting the official release changes what every workspace member installs, so run these steps on a CLI you own.

What you will build

An official release of acme-orders, a signed workspace install command, and a clean install of that release into a temporary home directory.

okibi clis release set  ->  hosting status (pendingRelease)  ->  signed install command  ->  acme-orders on PATH

AI Prompt

Using the Okibi CLI, publish the generated CLI acme-orders and install it the way a teammate would.

Requirements:
- `okibi clis releases acme-orders --json` lists immutable releases. A new CLI has one release, and it is already official.
- `okibi clis release set acme-orders --release <release-id>` makes a release official. Get the release id from `okibi clis releases`. `--run <run-id>` selects by run instead.
- `okibi clis hosting status acme-orders --json` reports `pendingRelease` and `releaseRebuilding` while a release builds. Wait until both are false and `workspaceInstallCommand` is present.
- Install visibility defaults to `workspace`. `okibi clis hosting visibility acme-orders public` changes it. Do not run it unless public access is intended.
- The install command contains a signed token that expires after one hour. Never commit it.
- Install into a temporary HOME and unset `CODEX_HOME` and `CLAUDE_CONFIG_DIR` so the test cannot touch the real environment.
- Run the verification step below before finishing.

Prerequisites

  • The Acme Orders example files, openapi.json (a fictional orders API spec) and server.py (a mock server for it). Download them into your working directory:

    curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json
    curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/server.py
    
  • A generated CLI named acme-orders (okibi generate --spec ./openapi.json --name acme-orders --agent).

  • To run the installed binary against the example API, start it (ACME_API_KEY=demo-key python3 server.py --port 8099) and export ACME_ORDERS_API_KEY=demo-key. The API's openapi.json and server.py are the two example files.

  • Okibi CLI 0.2.11, logged in.

Note: Signed tokens, workspace slugs and temp paths are replaced with placeholders.

1. Check the starting state

okibi clis releases acme-orders --json
{
  "officialReleaseId": "<release-id>",
  "releases": [
    { "id": "<release-id>", "releaseVersion": "1.0.0", "kind": "generation", "runNumber": 1, "hasArtifact": true, "rebuildable": true }
  ]
}

A new CLI has one release, and it is already official: officialReleaseId is set and hasArtifact is true. okibi clis show acme-orders --json shows the same under officialRelease. The release you want is the id of the first entry in releases. The real output also has section, officialRunId, runId, version, commitSha and publishedAt fields.

2. Set the official release

The first release is already official, so this call selects it again and changes nothing. You use the same command later to move the official release to a newer or an older one.

okibi clis release set acme-orders --release <release-id> --json
{ "cli": "acme-orders", "ok": true, "release_id": "<release-id>", "run_id": "" }

Use the id from step 1 as <release-id>. run_id is empty when you select by --release, and release_id is empty when you select by --run. The call succeeds either way.

3. Check hosting and get the install command

okibi clis hosting status acme-orders --json

If pendingRelease or releaseRebuilding is true, the release is still building. This loop waits up to two minutes for both to be false:

for i in $(seq 1 12); do
  okibi clis hosting status acme-orders --json | python3 -c "import json,sys;d=json.load(sys.stdin);sys.exit(1 if d['pendingRelease'] or d['releaseRebuilding'] else 0)" && break
  sleep 10
done; echo "ready after $i check(s)"

In this run the first check was already ready:

{
  "publishTarget": "hosted",
  "published": true,
  "installVisibility": "workspace",
  "publicRelease": { "version": 1, "releaseVersion": "1.0.0" },
  "pendingRelease": false,
  "releaseRebuilding": false,
  "workspaceInstallCommand": {
    "command": "curl -fsSL 'https://okibi.ai/i/<workspace>/acme-orders?t=<signed-token>' | sh",
    "expiresInMs": 3600000
  }
}

The response also includes a PowerShell form of the command under ps1. publishTarget is hosted, which means Okibi hosts the code. Publishing to your own GitHub account is a Pro option (okibi generate --destination github).

4. Install the release into a temporary home

CMD=$(okibi clis hosting status acme-orders --json | python3 -c "import json,sys;print(json.load(sys.stdin)['workspaceInstallCommand']['command'])")
T=$(mktemp -d)
env -u CODEX_HOME -u CLAUDE_CONFIG_DIR HOME=$T ACME_ORDERS_NO_KEYRING=1 sh -c "$CMD"
install: downloading acme-orders v1.0.0
install: checksum verified
install: installed to <temp-home>/.local/share/okibi/clis/acme-orders/versions/<n>
install: installed Agent Skill to <temp-home>/.agents/skills/acme-orders
install: symlinked <temp-home>/.local/bin/acme-orders
install: NOTE: <temp-home>/.local/bin is not on your PATH. Add this to your shell profile:
install:   export PATH="<temp-home>/.local/bin:$PATH"
install: done: installed acme-orders v1.0.0. Try: <temp-home>/.local/bin/acme-orders --help

The installer verifies a checksum, installs the binary and the matching agent skill, and prints a note when the bin directory is not on PATH.

Verify the result

HOME=$T ACME_ORDERS_NO_KEYRING=1 $T/.local/bin/acme-orders --version
HOME=$T ACME_ORDERS_NO_KEYRING=1 ACME_ORDERS_API_KEY=demo-key $T/.local/bin/acme-orders orders list --status pending --data-source live --no-cache --agent

Expected: acme-orders 1.0.0, followed by JSON with a results array of pending orders (ord_4 in the example data) and "meta": {"source": "live"}. The --data-source live --no-cache flags make the read go to the API, so a cached answer cannot pass for a live one. The second command needs the example API running. The installed CLI reads the API address stored in it, so no base-URL variable is needed.

The version shown is whichever release is official when you run this. After you publish a newer release (for example with okibi clis skill publish), the same install command installs that version instead (it showed 1.0.1 after one skill publish).

Clean up with rm -rf $T.

How it works

Releases are immutable snapshots of a generation or edit. Selecting one as official makes it the version the install route serves to workspace members. Each fetch of the installer script is counted in okibi clis insights as installerFetches. That counter records script fetches, not completed installs.

Common issues

A temporary HOME does not isolate the system keyring

The installer and the generated CLI store credentials in the operating system's keyring under one service name that every copy of acme-orders on the machine shares. Pointing HOME at a temporary folder does not change that. acme-orders uninstall deletes those keyring entries as well as files. Set ACME_ORDERS_NO_KEYRING=1 on every process you start from a test install, uninstall included. This guide's commands do. Keep CODEX_HOME and CLAUDE_CONFIG_DIR unset too, as above.

Selecting an older release moves the official release backwards

okibi clis release set acme-orders --release <older-release-id> makes that release official even when newer releases exist. A later okibi clis skill publish then fails with api 400: official-release-not-current until the newest release is selected again.

The install command expires

The token in the command expires after 3,600,000 ms. Request a fresh command from hosting status for each install.

Agent skills can still be linked into your real home

The installer also links the agent skill into agent directories it detects, and it reads CLAUDE_CONFIG_DIR and CODEX_HOME before it falls back to $HOME. If either variable is set in your shell, a test install with a temporary HOME can link the skill into that real directory. The env -u in step 4 prevents that. With it, only .agents and .local appeared in the temporary home, and no .claude or .codex directory.

Visibility stays on workspace

The release was installable only by workspace members.

npm and Homebrew are blocked for a hosted CLI

okibi clis npm status acme-orders --json and okibi clis homebrew status acme-orders --json both returned "blocker": "hosted-repo", with npm and homebrew null, while the official release was 1.0.2. The help text says Okibi publishes official releases to npm and to a Homebrew tap in the GitHub account that holds the CLI's code, so a CLI hosted by Okibi has no account to publish from.

Install paths and PATH

The installer places the binary under ~/.local/share/okibi/clis/<name>/versions/<n> and symlinks it into ~/.local/bin. If that directory is not on PATH, the installer prints the export PATH=... line to add.


verification:
  status: verified
  tested_at: "2026-10-30"
  product_version: "okibi 0.2.11; acme-orders 1.0.0"
  command: "HOME=$T ACME_ORDERS_NO_KEYRING=1 $T/.local/bin/acme-orders --version"
  expected_result: "acme-orders 1.0.0 while 1.0.0 is the official release. The release was ready on the first hosting status check; poll until pendingRelease and releaseRebuilding are false."

Related Articles