olam

@pleri/olam-cli

CLI for Olam — the agentic-thinking platform. Spawn isolated development worlds, dispatch tasks to coding agents inside them, capture thought graphs they produce, ship PRs from inside worlds, and orchestrate parallel sub-tasks ("lanes") under one world.

This is the published artifact repository. Source lives in pleri/olam. Filing issues against this repo is fine for install/distribution problems; functionality issues belong in the source repo.

Install

Claude Code operators — via shuk marketplace (recommended)

claude plugin marketplace add pleri/shuk
claude plugin install olam@shuk

Restart Claude Code. The MCP server boots on first /olam:* slash command. See plugin/README.md for plugin install paths (shuk, olam mcp install, upgrade, offline git-clone fallback) + the dual-mode .mcp.json rationale.

CLI-only — via curl installer

curl -fsSL https://olam.bar.dev/install | sh

The installer:

1. Detects your npm prefix and verifies it's writable (offers a user-local fallback if not)
2. Authenticates npm against GitHub Packages using your gh CLI token (refreshes scope if missing read:packages)
3. Runs npm install -g @pleri/olam-cli@stable
4. Prompts you to run olam setup to finish per-machine bootstrap

CLI-only — manual

# 1. Authenticate npm against GitHub Packages
npm login --scope=@pleri --registry=https://npm.pkg.github.com

# 2. Install
npm install -g @pleri/olam-cli@stable

# 3. Bootstrap
olam setup

You'll need a GitHub PAT with read:packages scope (and access to the pleri org).

Command surface

Olam organizes capability into a small number of command groups. Every group has --help.

World lifecycle

olam create my-task --task "implement feature X"   # spawn a new isolated world
olam list                                          # show running worlds
olam status [<world-id>]                           # machine status or per-world details
olam enter <world-id>                              # open a terminal inside a world
olam destroy <world-id>                            # tear down a world and clean up
olam clean                                         # reclaim stale worlds + orphan resources
olam observe <world-id>                            # stream the agent's reasoning (live)

Dispatch & thought capture

olam dispatch <world-id> "next prompt"             # send a follow-up prompt to a running world
olam crystallize <world-id>                        # save the world's thought graph to the Pleri Plane

Lanes — parallel sub-tasks under one world

olam lanes list <world-id>
olam lanes create <world-id> <lane-name>
olam lanes dispatch <world-id> <lane-name> "prompt"
olam lanes destroy <world-id> <lane-name>
olam lanes merge <world-id> <lane-name>            # merge a lane's branch back into the world

PR workflow — file + decide from inside the world

olam pr list <world-id>                            # PR-gate requests from the world's agent
olam pr show <world-id> <pr-id>
olam pr track <pr-id>                              # follow status of a PR you've filed
olam pr approve <pr-id>
olam pr reject <pr-id> --reason "..."

Workspaces & repos — multi-project orchestration

olam workspace list
olam workspace add <name> --path <dir>
olam workspace show <name>
olam workspace remove <name>

olam repos list                                    # repos visible in the active workspace
olam repos add <git-url>
olam repos remove <name>
olam repos update                                  # pull all

Knowledge graph — per-world symbol index

olam kg build [<world-id>]                         # build the graphify-backed graph
olam kg status [<world-id>]                        # build progress + freshness
olam kg watch [<world-id>]                         # re-build on file change
olam kg classify <world-id> --rules <file>         # apply classification rules
olam kg doctor [<world-id>]                        # diagnose graph health

Agents inside worlds query the graph via the registered MCP server; prefer it over raw grep for symbol-shaped questions (see docs/decisions/014-kg-first-search.md in the source repo).

Runbooks — canonical procedures replayable in worlds

olam runbooks list
olam runbooks show <name>
olam runbooks add <name> --file <markdown>
olam runbooks apply <name> <world-id>
olam runbooks remove <name>

Auth — credential vault for Claude / GitHub / npm

olam auth up                                       # bring the auth-service vault up
olam auth down                                     # take it down
olam auth status
olam auth login <provider>                         # claude, github, npm
olam auth logout <provider>
olam auth refresh <provider>
olam auth list
olam auth disable <id>
olam auth enable <id>
olam auth remove <id>