> ## Documentation Index
> Fetch the complete documentation index at: https://ixoworld-mintlify-9a7944b6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every qiforge-cli command — installation, authentication, oracle scaffolding, plugin scaffolding, entity ops, chat.

The CLI installs from the `qiforge-cli` npm package and runs as the `qiforge-cli` binary ([source](https://github.com/ixoworld/ixo-oracles-cli)). It scaffolds new oracles, scaffolds new plugins inside an existing oracle, provisions on-chain identity + Matrix bots, and gives you an SSE chat client for testing.

## Installation

```sh theme={null}
npm install -g qiforge-cli
# or
pnpm add -g qiforge-cli
```

**pnpm users:** after install, approve build scripts for `protobufjs`:

```sh theme={null}
pnpm approve-builds -g
# select protobufjs when prompted
```

Verify:

```sh theme={null}
qiforge-cli --help
```

Requires Node 22+. Authentication needs either the IXO Mobile App (SignX QR) or a 12/24-word mnemonic (offline mode).

## Commands at a glance

| Command                             | Purpose                                                |
| ----------------------------------- | ------------------------------------------------------ |
| `qiforge-cli`                       | Interactive menu (auth → choose command).              |
| `qiforge-cli new <name>`            | Scaffold a new oracle from the bundled starter.        |
| `qiforge-cli plugin new <name>`     | Scaffold a new plugin into an existing oracle project. |
| `qiforge-cli create-entity`         | Create the on-chain entity record + Matrix bot.        |
| `qiforge-cli update-entity`         | Update an existing entity (e.g. add controllers).      |
| `qiforge-cli update-oracle-api-url` | Update the oracle's registered API URL/domain.         |
| `qiforge-cli setup-encryption-key`  | Provision the oracle's encryption/signing key.         |
| `qiforge-cli create-composio-key`   | Mint a Composio API key tied to the oracle.            |
| `qiforge-cli create-user`           | Create a new user account.                             |
| `qiforge-cli signx-login`           | Authenticate via SignX QR (IXO Mobile App).            |
| `qiforge-cli offline-login`         | Authenticate with a local mnemonic (no mobile app).    |
| `qiforge-cli logout`                | Clear stored credentials.                              |
| `qiforge-cli help`                  | Show help.                                             |
| `--chat`                            | Flag — start a chat session with a running oracle.     |
| `--help`, `-h`                      | Flag — show help.                                      |

## Authentication

Two modes:

<AccordionGroup>
  <Accordion title="SignX (default)" icon="qrcode">
    Uses the IXO Mobile App for QR-code-based authentication. Keep the app open during the session.

    ```sh theme={null}
    qiforge-cli signx-login
    # Scan the QR code with the IXO Mobile App when prompted.
    ```
  </Accordion>

  <Accordion title="Offline wallet" icon="key">
    Uses a local mnemonic. No mobile app needed. Credentials are stored in `~/.wallet.json`.

    Interactive:

    ```sh theme={null}
    qiforge-cli offline-login
    ```

    Non-interactive:

    ```sh theme={null}
    qiforge-cli offline-login \
      --network devnet \
      --mnemonic "your twelve word mnemonic phrase here" \
      --matrixPassword "your-matrix-password"
    ```

    **Flags:**

    | Flag               | Description                                       |
    | ------------------ | ------------------------------------------------- |
    | `--network`        | `devnet`, `testnet`, `mainnet`                    |
    | `--mnemonic`       | Mnemonic phrase for wallet derivation.            |
    | `--matrixPassword` | Matrix account password.                          |
    | `--name`           | Display name (falls back to Matrix profile name). |
  </Accordion>
</AccordionGroup>

## qiforge-cli new

Scaffolds a new oracle from the bundled starter template — no git clone. Interactive by default: it walks you through auth, network, the oracle profile, and entity creation, then writes the project.

```sh theme={null}
qiforge-cli new my-oracle
```

Non-interactive (for CI) — `--name` is required:

```sh theme={null}
qiforge-cli new --no-interactive \
  --name my-oracle \
  --description "What this oracle does" \
  --org "My Org" \
  --install
```

**Flags:**

| Flag               | Description                                      | Default    |
| ------------------ | ------------------------------------------------ | ---------- |
| `--name`           | Project name (required with `--no-interactive`). | —          |
| `--path`           | Directory to scaffold into.                      | `./<name>` |
| `--template`       | Starter template.                                | `basic`    |
| `--description`    | Oracle description.                              | —          |
| `--org`            | Organisation name.                               | `IXO`      |
| `--install`        | Run the package install after scaffolding.       | `false`    |
| `--force`          | Overwrite an existing directory.                 | `false`    |
| `--no-interactive` | Skip prompts (requires `--name`).                | `false`    |

The command optionally runs the install step and can also create the oracle entity + Matrix account in the same flow.

## qiforge-cli plugin new

Scaffolds a new plugin into an **existing** oracle project. Run it from inside the project; the CLI walks up to find a `package.json` that depends on `@ixo/oracle-runtime` and writes the plugin there.

```sh theme={null}
qiforge-cli plugin new climate
```

**Flag:** `--cwd` — the directory to resolve the oracle project from (defaults to the current directory).

Generated layout (under `src/plugins/<name>/`):

```text theme={null}
src/plugins/climate/
├── climate.plugin.ts          # OraclePlugin class with a manifest stub + one sample tool
├── climate.plugin.test.ts     # 3 tests using createTestRuntime
├── climate.fixtures/          # placeholder for fixtures
└── README-climate.md          # the manifest mirrored as docs
```

Name validation: kebab-case, must not collide with bundled plugin names.

## qiforge-cli create-entity

Creates the on-chain entity record and Matrix bot, and writes `oracle.config.json` + `.env`. Used both standalone (e.g. when re-provisioning) and as part of `new`.

```sh theme={null}
qiforge-cli create-entity --no-interactive \
  --network devnet \
  --oracle-name "My Oracle" \
  --price 100 \
  --org-name "My Org" \
  --description "Oracle description" \
  --api-url http://localhost:4000 \
  --model "anthropic/claude-sonnet-4" \
  --pin 123456
```

<Note>
  `create-entity` registers `--api-url http://localhost:4000` by default, but the runtime's own default `PORT` is `3000`. If you take the default URL, make your running oracle reachable at it: either set `PORT=4000` in your `.env` to match, or update the registered URL later with `qiforge-cli update-oracle-api-url`.
</Note>

**Flags:**

| Flag                    | Description                          | Default                 |
| ----------------------- | ------------------------------------ | ----------------------- |
| `--network`             | `devnet`, `testnet`, `mainnet`.      | `devnet`                |
| `--oracle-name`         | Oracle name.                         | `My oracle`             |
| `--price`               | Price in IXO credits.                | `100`                   |
| `--org-name`            | Organisation name.                   | `IXO`                   |
| `--logo`                | Logo URL.                            | Auto-generated.         |
| `--cover-image`         | Cover image URL.                     | Same as logo.           |
| `--location`            | Location string.                     | `New York, NY`          |
| `--description`         | Entity description.                  | Default placeholder.    |
| `--website`             | Website URL.                         | —                       |
| `--api-url`             | Oracle API URL.                      | `http://localhost:4000` |
| `--project-path`        | Project directory for saving config. | Current directory.      |
| `--pin`                 | 6-digit PIN for Matrix vault.        | Prompted.               |
| `--model`               | LLM model identifier.                | `moonshotai/kimi-k2.5`  |
| `--skills`              | Comma-separated skill list.          | —                       |
| `--prompt-opening`      | Opening prompt for the oracle.       | —                       |
| `--prompt-style`        | Communication style.                 | —                       |
| `--prompt-capabilities` | Capabilities description.            | —                       |
| `--mcp-servers`         | JSON array `[{"url":"..."}]`.        | —                       |

Supported model identifiers (from the interactive menu):

```text theme={null}
moonshotai/kimi-k2.5             # default
anthropic/claude-sonnet-4
openai/gpt-4o
google/gemini-2.5-pro
meta-llama/llama-4-maverick
```

Or pass any custom identifier as `--model`.

## qiforge-cli update-entity

Updates an existing entity. Used to add controllers, rotate keys, or modify metadata after the initial create-entity.

```sh theme={null}
qiforge-cli update-entity
```

Accepts account DIDs as controllers (in addition to entity DIDs).

## qiforge-cli update-oracle-api-url

Updates the URL the oracle entity advertises. Default is `http://localhost:4000`; switch to your deployed URL before going live.

```sh theme={null}
qiforge-cli update-oracle-api-url
```

## qiforge-cli setup-encryption-key

Provisions the oracle's encryption/signing key into its Matrix account room — the P-256 `keyAgreement` key used to decrypt per-room secrets, plus the signing material the runtime uses to mint downstream UCAN invocations. Until it's provisioned, authenticated routes return 401 and the boot log warns about the missing key.

```sh theme={null}
qiforge-cli setup-encryption-key
```

Run it once per oracle (and again after rotating the key).

## qiforge-cli create-composio-key

Mints a Composio API key tied to your oracle's DID. Required if your oracle uses the bundled `composio` plugin.

```sh theme={null}
qiforge-cli create-composio-key
```

Prompts for the oracle DID and a key label, then writes the key to your Composio account.

## qiforge-cli create-user

Creates a new user account (DID + Matrix account) — useful for testing your oracle against multiple identities.

```sh theme={null}
qiforge-cli create-user
```

## --chat

Starts a chat session with a running oracle over SSE — renders tool calls, assistant messages, and errors in the terminal. It's a flag, not a subcommand:

```sh theme={null}
qiforge-cli --chat
```

Interactive — prompts for the oracle URL (or uses the saved one from `new`).

## qiforge-cli logout

```sh theme={null}
qiforge-cli logout
```

Clears stored authentication. Future commands prompt for auth again.

## What `qiforge-cli new` writes

```text theme={null}
my-oracle/
├── src/
│   ├── main.ts                 # calls createOracleApp({ config, plugins })
│   ├── config.ts               # OracleConfig
│   └── plugins/                # your plugins go here
├── .claude/
│   └── skills/qiforge-oracle/  # Claude Code skill (project-local)
├── .env                        # Tier-0 vars + initial plugin vars
├── oracle.config.json          # name, model, prompt, entityDid, …
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── CLAUDE.md                   # bootstrapping for Claude Code
```

The CLI also scaffolds a **`qiforge-oracle` Claude Code skill** at `.claude/skills/qiforge-oracle/` so any AI agent you point at the project (Claude Code, Cursor, etc.) immediately has dense, scenario-specific guidance on the framework — adding plugins, adding tools, wiring env, writing tests with `createTestRuntime`, debugging boot. The skill is project-local: it ships inside every scaffolded oracle, no separate install needed. See the [skill source](https://github.com/ixoworld/ixo-oracles-cli/tree/main/src/templates/starter/.claude/skills/qiforge-oracle) in the CLI repo.

Generated `.env` skeleton:

```text theme={null}
PORT=3000
ORACLE_NAME=your-oracle-name
NETWORK=devnet

MATRIX_BASE_URL=https://matrix.ixo.world
MATRIX_ORACLE_ADMIN_USER_ID=...
MATRIX_ORACLE_ADMIN_PASSWORD=...
MATRIX_ORACLE_ADMIN_ACCESS_TOKEN=...
MATRIX_ACCOUNT_ROOM_ID=...
MATRIX_VALUE_PIN=...
MATRIX_RECOVERY_PHRASE=...

BLOCKSYNC_GRAPHQL_URL=https://devnet-blocksync-graphql.ixo.earth/graphql
RPC_URL=https://devnet.ixo.earth/rpc/
ORACLE_DID=did:ixo:ixo1...
ORACLE_ENTITY_DID=did:ixo:entity:...
SECP_MNEMONIC=...
SQLITE_DATABASE_PATH=./.data/sqlite

LLM_PROVIDER=openrouter
OPEN_ROUTER_API_KEY=

LANGSMITH_API_KEY=
LANGSMITH_PROJECT=
```

Fill in the plugin-specific vars before booting.

## Related references

* [Identity and auth guide](/build-an-oracle/develop/identity-and-auth) — what `create-entity` and `setup-encryption-key` set up.
* [Environment variables](/build-an-oracle/reference/environment-variables) — what to put in the `.env` the CLI writes.
* [CLI source](https://github.com/ixoworld/ixo-oracles-cli) — every command's implementation.