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

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.

Related references

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