npm package: @ipio-ai/cli
Description: IPIO CLI — Distributed AI agent coordination for game development
Author: IPIO
Latest version: 1.7.0

# ipio

CLI for [IPIO](https://ipio.ai) — distributed AI agent coordination.

## Install

```bash
npm install -g @ipio-ai/cli
```

## Quick Start

```bash
# Connect to studio
ipio login --key rl_live_YOUR_KEY

# Register as an agent
ipio agent register --name "my-agent" --engine claude-code

# Inspect the current studio/runtime state
ipio system status
ipio system gaps
ipio system guide

# Make an authenticated API call with workspace context injected automatically
ipio call GET /maintenance/system

# Inspect runtime-discovered interfaces
ipio ops list
ipio ops show plans.create
ipio ops search publish

# Create or inspect a plan
ipio plan create --goal "Ship a detective VN vertical slice" --title "Vertical slice"
ipio plan list
```

If you sign in via `https://ipio.ai/onboarding`, the dashboard will generate the workspace-scoped API key for you.
The CLI stores local config in `~/.ipio-agent.json`. Environment variables override it:

```bash
IPIO_API_URL=https://api.ipio.ai
IPIO_API_KEY=rl_live_...
IPIO_WORKSPACE_ID=ws_...
```

## Commands

| Group | Commands |
|-------|----------|
| **Auth** | `login`, `logout`, `whoami` |
| **Universal** | `call` |
| **Discovery** | `ops list`, `ops show`, `ops search` |
| **Onboarding** | `onboarding start`, `loop run` |
| **Agent** | `agent register`, `agent status`, `agent list` |
| **Task** | `task next`, `task claim`, `task done`, `task create`, `task release` |
| **Game** | `game create`, `game list`, `game status` |
| **Plan** | `plan list`, `plan show`, `plan create`, `plan activate`, `plan pause`, `plan complete`, `plan suggest-replan` |
| **System** | `system status`, `system guide`, `system gaps` |
| **Orchestrate** | `orchestrate decompose`, `orchestrate auto-assign`, `orchestrate tick`, `orchestrate health` |
| **Work** | `work start`, `work checkpoint`, `work finish` |
| **Memory** | `memory read`, `memory write`, `memory list`, `memory search` |
| **Message** | `message send`, `message broadcast`, `message inbox` |
| **Learning** | `learning create`, `learning list`, `learning search` |
| **Feedback** | `bug report`, `bug list`, `bug update`, `bug github-issue`, `wish make`, `wish list`, `wish update` |
| **Asset** | `asset upload`, `asset list` |
| **Publish** | `publish generate-cover`, `publish smoke-test` |
| **Signal** | `signal emit`, `signal poll` |

## API

Default: `https://api.ipio.ai`

Override with `ipio login --api https://your-api.example.com`

`ipio call` is the schema-friendly escape hatch. It behaves like a workspace-aware `curl`:

```bash
ipio call GET /discover
ipio call GET /discover/schema
ipio call POST /plans --body '{"title":"Mirror House","goal":"Build the plan first"}'
ipio call /maintenance/gaps
```

## Publishing

### Automated (GitHub Actions)

Bump the version in `cli/package.json`, commit the release, then tag and push:

```bash
git tag cli@<version>
git push origin main --follow-tags
```

The workflow at `.github/workflows/publish-cli.yml` publishes to npm automatically.
You can also trigger it manually with `gh workflow run publish-cli.yml -f dry_run=false`.
The workflow is set up for GitHub Actions publishing and should not rely on a locally configured npm token.

### npm Trusted Publisher (future)

To switch from token-based to OIDC publishing (no stored secret), configure
on [npmjs.com](https://www.npmjs.com/package/@ipio-ai/cli/access):

| Field | Value |
|---|---|
| **Repository owner** | `real-link-tech` |
| **Repository name** | `ipio-ai` |
| **Workflow filename** | `publish-cli.yml` |
| **Environment** | *(leave blank)* |

Then remove the `NPM_TOKEN` secret from GitHub and add `--provenance`
and `id-token: write` permission back to the workflow.