CLI reference

The CLI installs from the qiforge-cli npm package and runs as the qiforge-cli binary (source). 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

npm install -g qiforge-cli
# or
pnpm add -g qiforge-cli

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

pnpm approve-builds -g
# select protobufjs when prompted

Verify:

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:

SignX (default)

Uses the IXO Mobile App for QR-code-based authentication. Keep the app open during the session.

qiforge-cli signx-login
# Scan the QR code with the IXO Mobile App when prompted.

Offline wallet

Uses a local mnemonic. No mobile app needed. Credentials are stored in ~/.wallet.json.

Interactive:

qiforge-cli offline-login

Non-interactive:

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).

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.

qiforge-cli new my-oracle

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

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.

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>/):

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.

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.

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):

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.

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.

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.

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.

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.

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:

qiforge-cli --chat

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

qiforge-cli logout

qiforge-cli logout

Clears stored authentication. Future commands prompt for auth again.

What `qiforge-cli new` writes

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 in the CLI repo.

Generated .env skeleton:

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.

Identity and auth guide — what create-entity and setup-encryption-key set up.
Environment variables — what to put in the .env the CLI writes.
CLI source — every command's implementation.

CLI reference

Installation

Commands at a glance

Authentication

qiforge-cli new

qiforge-cli plugin new

qiforge-cli create-entity

qiforge-cli update-entity

qiforge-cli update-oracle-api-url

qiforge-cli setup-encryption-key

qiforge-cli create-composio-key

qiforge-cli create-user

--chat

qiforge-cli logout

What qiforge-cli new writes

Related references

What `qiforge-cli new` writes