# ixora

CLI for managing ixora AI agent deployments on IBM i — and for talking to the running AgentOS.

> [!TIP]
> Full documentation lives in [`docs/`](docs/README.md) — every command, every flag, with examples. Start with [Getting Started](docs/getting-started.md) or browse the [docs index](docs/README.md).

## Install

```sh
npm install -g @ibm/ixora
```

Or run directly with npx:

```sh
npx @ibm/ixora stack install
```

### Requirements

- Node.js >= 22
- Docker Desktop (or Podman)
- An IBM i system with Db2 for i
- An API key for your chosen model provider (Anthropic, OpenAI, Google, or Ollama for local)

## Quick Start

```sh
ixora stack install    # Interactive setup (IBM i connection, model provider, profile)
ixora stack start      # Start services (defaults to --profile full = DB + API + MCP + UI)
ixora stack stop       # Stop services
```

Once an instance is up, talk to AgentOS directly:

```sh
ixora agents list      # List registered agents
ixora agents run <id> "what's running on QSYS?"
ixora chat             # Interactive chat TUI (agents, teams, workflows)
ixora traces list      # See recent runs
ixora sessions list    # Browse sessions
ixora knowledge bases  # List knowledge bases (e.g. "User Documents")
ixora knowledge search "..."
```

Attach a knowledge base to an agent by its display name when you create or
update it:

```sh
ixora agents create --name "Docs Helper" --id docs-helper \
  --model anthropic:claude-sonnet-4-6 --knowledge "User Documents"
```

If only one instance is available, those commands target it implicitly. With 2+ instances available you have two options:

```sh
ixora --instance prod agents list           # one-off override
ixora instances default prod                # set a persistent default
ixora agents list                         # now uses 'prod' implicitly
ixora --instance dev agents list            # flag still wins over the default
ixora instances default --clear             # back to "must specify --instance"
```

### The AgentOS directory (`ixora instances`)

`ixora instances` is the one place to see and target every AgentOS, regardless of how it was created — **stack** local stacks, **external** URLs, and **workspace** codebases:

```sh
ixora instances                             # directory: ID + URL + KIND + running indicator
ixora instances list --json                 # scriptable (flat array)
ixora instances default prod                # set/clear the default target
ixora instances remove <id>                 # remove any instance from the directory
```

### External AgentOS endpoints

Beyond the IBM i stacks ixora provisions ("stack" instances), you can register **any AgentOS-compatible URL** as a target — typically another locally-running AgentOS instance you spun up from a different template, but the URL can be remote too. ixora doesn't lifecycle-manage these ("external" instances); it just routes runtime commands at them.

```sh
ixora instances add                                          # interactive
ixora instances add --id personal \
  --agentos-url http://localhost:8080 [--agentos-key sk-xxx] # non-interactive

ixora instances                                              # directory: KIND + URL + running indicator
ixora --instance personal agents list                        # target the external by name
```

Externals always count as "available" (no docker container check), so the implicit-pick rule extends naturally: 1 available → pick it; 2+ → require `--instance` (or `IXORA_DEFAULT_INSTANCE`). The optional `--agentos-key` is stored as `SYSTEM_<ID>_AGENTOS_KEY` in `~/.ixora/.env`.

## Two command surfaces

The `ixora` binary exposes two trees:

| Tree | Purpose | Examples |
|---|---|---|
| `ixora stack ...` | Manage the local stack: install, start/stop, configure, add IBM i systems | `ixora stack install`, `ixora stack add`, `ixora stack config set ...` |
| `ixora <runtime> ...` | Talk to the running AgentOS (ported from the standalone `agno-cli`) | `ixora agents`, `ixora teams`, `ixora workflows`, `ixora traces`, `ixora sessions`, `ixora knowledge`, `ixora memories`, `ixora evals`, `ixora approvals`, `ixora schedules`, `ixora metrics`, `ixora databases`, `ixora registries`, `ixora components`, `ixora models`, `ixora status` |

`ixora <runtime>` commands always pick a target instance (the only running one by default; `--instance <name>` to choose). `ixora stack` commands are unaffected by `--instance` — they have their own targeting (`ixora stack start <id>`, etc.). The third surface, **`ixora instances`**, is the cross-kind directory: it lists and targets every AgentOS (stack, external, workspace) and registers external URLs. A fourth, **`ixora workspace`**, scaffolds and runs standalone AgentOS workspaces from starter templates via Docker — it talks to Docker directly and never consumes `--instance`/`--url`.

### Deployment shapes (`--profile`)

| Profile | Containers | Use case |
|---|---|---|
| `full` (default) | DB + API + MCP + Carbon UI | Local development, the bundled web UI |
| `mcp`            | DB + API + MCP             | Backend-only — bring your own UI, or run as a service |

```sh
ixora stack start --profile full  # All four services (default)
ixora stack start --profile mcp   # No Carbon UI; API on :18000, DB on :15432
```

The chosen profile is persisted to `~/.ixora/.env`, so subsequent `stop`/`status`/`logs`/`restart`/`upgrade` calls without `--profile` keep the same shape. Switching mid-session is safe: `ixora stack stop --profile mcp` while in `full` leaves the UI container untouched.

The old `--profile api` is accepted as an alias for `--profile mcp` (with a one-line warning). The removed `--profile cli` is likewise coerced to `mcp` — agents now always reach IBM i through the MCP server. See [IXORA_QUICKSTART.md](IXORA_QUICKSTART.md) → §8 "Stack profiles".

### Per-system database isolation

By default each IBM i system gets its **own** `ai_<id>` Postgres database (and its own `/data` volume) inside the shared `agentos-db` container — so sessions, memory, knowledge, and learnings are isolated per system. A single-instance deployment is just `agentos-db` with an `ai_default` database (nothing extra); with 2+ instances a one-shot `db-init` service provisions the additional databases. To put everything back in one shared `ai` database instead: `ixora stack config set IXORA_DB_ISOLATION shared && ixora stack restart`. See [IXORA_QUICKSTART.md](IXORA_QUICKSTART.md) → §4 "Advanced: per-system database isolation".

## Stack commands

| Command | Description |
|---------|-------------|
| `stack install` | First-time setup (interactive) |
| `stack register` | Store the private-preview access token and log in to ghcr.io |
| `stack start` | Start services |
| `stack stop` | Stop services |
| `stack restart [service]` | Restart all or a specific service |
| `stack status` | Show service status and deployed profile |
| `stack upgrade` | Pull latest images and restart |
| `stack uninstall` | Stop services and remove images |
| `stack logs [service]` | Tail service logs |
| `stack version` | Show CLI and image versions |
| `stack config show` | Show current configuration |
| `stack config set <key> <value>` | Update a config value |
| `stack config edit` | Open config in your editor |
| `stack add` | Provision a new **stack**-kind (local) IBM i instance. Flags: `--id ... --name ...`. (External URLs → `ixora instances add`.) |
| `stack remove <id>` | Remove a stack instance (cleans up env keys; also available as `ixora instances remove`) |
| `stack list` | List **stack** instances with URL + PACKS columns (see `ixora instances` for all kinds) |
| `stack start\|stop\|restart <id>` | Manage one stack instance's containers (errors with a hint if `<id>` is external) |
| `stack packs list [instance]` | List packs the deployed image declares and which are enabled on an instance |
| `stack models list\|add\|set\|show` | Manage the model registry: list configured models, add one, set the base model or a team-member/team-leader override |
| `stack packs select [instance]` | Choose which packs are enabled on an instance (pack picker) |
| `stack connection show [instance]` | Show an instance's IBM i JDBC options (read-only `access` by default) |
| `stack connection set\|unset <instance> <key> [value]` | Set / remove a JDBC option (library list, naming, `access`, …) |

## AgentOS directory (`ixora instances`)

The cross-kind registry of every AgentOS you can target — stack, external, and workspace.

| Command | Description |
|---------|-------------|
| `instances list` | List every instance (stack/external/workspace) with a live running indicator. `--json [fields]` for a scriptable array. Default subcommand — `ixora instances` alone runs it. |
| `instances add` | Register an external AgentOS URL. Flags: `--id ... --name ... --agentos-url ... --agentos-key ...` |
| `instances remove <id>` | Remove any instance from the directory (stack/external/workspace; cleans up env keys) |
| `instances default [id] [--clear]` | Show, set, or clear the default target used when 2+ are available and `--instance` is omitted |

## Workspaces (`ixora workspace`)

Scaffold, run, and tear down standalone AgentOS workspaces (cloned starter templates) with Docker. Workspace commands talk to Docker directly and never consume `--instance`/`--url`. See [docs/workspace.md](docs/workspace.md) for the full reference.

| Command | Description |
|---------|-------------|
| `workspace create` | Clone a starter template into a new directory and register it as a `workspace` instance. Flags: `-t ibmi-agentos-docker\|ibmi-agentos-openshift`, `-u <git-url>`, `-n <name>`, `--port <n>` (container port for `ixora instances` URL discovery; default `8000`) |
| `workspace up [filter]` | Create the workspace's resources (or run its Compose file) |
| `workspace down [filter]` | Delete the workspace's resources |
| `workspace patch [filter]` | Update existing resources |
| `workspace restart [filter]` | `down` then `up` |
| `workspace config` | Print the active workspace's config |
| `workspace delete [--name <name>]` | Remove a workspace record (does not delete files) |

## AgentOS runtime commands

| Command | Description |
|---------|-------------|
| `chat [--agent\|--team\|--workflow <id>]` | Interactive chat TUI: streamed runs, tool rendering, inline confirmations (TTY only) |
| `agents list\|get\|run\|continue\|cancel\|create\|apply\|update\|set-model\|delete` | Manage agents (including the agent definition itself) |
| `teams list\|get\|run\|continue\|cancel\|set-model` | Manage teams |
| `workflows list\|get\|run\|continue\|cancel` | Manage workflows **(gated — off by default)** |
| `traces list\|get\|stats\|search` | Inspect traces |
| `sessions list\|get\|create\|update\|delete\|delete-all\|runs` | Manage sessions |
| `memories list\|get\|create\|update\|delete\|delete-all\|topics\|stats\|optimize` | Manage memories |
| `knowledge bases\|upload\|list\|get\|search\|status\|delete\|delete-all\|config` | Manage knowledge bases (`bases` lists them; upload/search/etc. target one) |
| `evals list\|get\|delete` | Manage eval runs **(gated — off by default)** |
| `approvals list\|get\|resolve` | Manage approvals **(gated — off by default)** |
| `schedules list\|get\|create\|update\|delete\|pause\|resume\|runs` | Manage schedules **(gated — off by default)** |
| `metrics get\|refresh` | View / refresh metrics |
| `databases migrate <db_id>` | Run database migrations |
| `registries list` | List registry items |
| `components list\|get\|create\|update\|delete\|config ...` | Manage components in AgentOS |
| `models list` | List available models in AgentOS (agents, team members, and the configured catalog) |
| `status` | Show AgentOS server status and resource overview |
| `health` | Ping `/health` on the resolved instance; reports status + uptime + latency (exits non-zero when unhealthy) |
| `docs` | Inspect the AgentOS server's raw HTTP API via `/openapi.json` |

### Gated commands (`ixora features`)

`workflows`, `evals`, `approvals`, `schedules`, and `workspace` are **off by
default** — hidden from `--help` and not runnable. Each is enabled independently:

```bash
ixora features list                 # show every gated feature and its state
ixora features enable workflows     # turn one on (persists to ~/.ixora/config.yaml)
ixora features enable evals schedules
ixora features disable workflows
```

Running a disabled command prints how to enable it and exits non-zero. For
CI/one-off use, an environment override skips the config file:

```bash
IXORA_FEATURE_WORKFLOWS=1 ixora workflows list   # this invocation only
```

Precedence: `IXORA_FEATURE_<NAME>` (env) → `~/.ixora/config.yaml` → off.

## Global options

```
# Stack shape & install-time
--profile <name>       Stack shape: full / mcp  [default: full]
--packs <ids>          Packs to enable at install: comma-separated ids, or 'all' (install-time)
--image-version <tag>  Pin image version (e.g., v1.2.0)
--no-pull              Skip pulling images
--purge                Remove volumes too (with uninstall)
--runtime <name>       Force docker or podman

# AgentOS targeting (consumed by ixora <runtime> ... commands)
-i, --instance <name>  Target a specific configured instance. Implicit when only one is
                       running, or when the configured default (ixora instances default)
                       is in the running set. Always wins when supplied.
--url <url>            Override AgentOS endpoint entirely (skips instance resolution)
--key <key>            Override AgentOS API key for this invocation
--timeout <seconds>    Override request timeout in seconds
--no-color             Disable color output
--json [fields]        Emit JSON; `--json id,name` projects fields
-o, --output <format>  Output format: json, table, or compact (auto-detects from TTY)
```

## Use with Claude Code (skill)

This repo doubles as a [Claude Code plugin marketplace](https://docs.anthropic.com/en/docs/claude-code/plugins) exposing the `use-ixora` skill, which teaches Claude how to drive the Ixora platform with this CLI — installing the stack, managing multiple instances (stack and external), running agents, inspecting traces, browsing knowledge, and more.

**Via the `ixora` CLI (recommended):**

```sh
ixora skills install          # add --global to install to your user directory
ixora skills install --agent claude-code cursor   # target specific coding agents
ixora skills update           # pick which installed skills to refresh (--global for user dir)
```

The skills ship **inside the `@ibm/ixora` package**, so `ixora skills install`
installs them from your local install using the
[`skills`](https://github.com/vercel-labs/skills) installer — **no GitHub or repo
access required**. By default it auto-detects your coding agents; pass `--agent`
to target specific ones. `ixora skills list` shows what it installs. `ixora skills
update` re-syncs the installed skills from your current `@ibm/ixora` (upgrade the
CLI to get newer skills) — it shows a picker of the installed Ixora skills (all
pre-selected) and refreshes the ones you keep checked; add `--yes` to update them
all non-interactively.

**Via the Claude Code marketplace** (requires access to the private `ibmi-agi/ixora-cli` repo):

```sh
claude plugin marketplace add ibmi-agi/ixora-cli
claude plugin install use-ixora@ixora-cli
```

Once installed, Claude activates the skill automatically based on context — e.g. "install ixora", "add a new ixora instance", "run an agent on prod", "inspect that trace" — or you can invoke it explicitly as `/ixora-cli:use-ixora`.

## Development

```sh
git clone https://github.com/ibmi-agi/ixora-cli.git
cd ixora-cli
npm install
npm run build
npm link          # Makes 'ixora' available globally

npm test          # Run tests
npm run dev -- <command>  # Run without building
```

---

## Legacy: Shell Script Version

The original `ixora.sh` shell script is still available in this repo for reference. To install it directly:

```sh
curl -LsSf https://raw.githubusercontent.com/ibmi-agi/ixora-cli/main/install.sh | sh
```

This installs the shell script to `~/.local/bin/ixora`. The Node.js CLI above is the recommended version going forward. (The shell script does not include the AgentOS runtime commands — only the stack-management surface.)