CLI reference

The CLI installs from the qiforge-cli npm package and runs as the qiforge-cli binary (source). It provisions an oracle's on-chain identity and Matrix account, scaffolds the oracle as a Cloudflare Workers project on @ixo/oracle-runtime-workers, scaffolds plugins inside it, and manages the entity and its keys afterwards. This page describes qiforge-cli 2.0.0.

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 --version
qiforge-cli --help

Requires Node 22+ and pnpm 10+. Provisioning needs either the IXO Mobile App (SignX QR) or a 12/24-word mnemonic (offline mode). Deploying the scaffolded oracle needs a Cloudflare account on the Workers Paid plan.

Commands at a glance

Authentication

Two modes. Either one keeps the session in ~/.wallet.json; qiforge-cli logout clears it.

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

qiforge-cli offline-login

qiforge-cli offline-login \
  --network devnet \
  --mnemonic "your twelve word mnemonic phrase here" \
  --matrixPassword "your-matrix-password"

qiforge-cli new

Provisions an oracle and scaffolds it as a Cloudflare Workers project, from the bundled template (no git clone). Interactive by default: it asks for the name, description, organisation, avatar and network, provisions the oracle, asks you to describe the services for its Agent Card, and writes the project.

qiforge-cli new

Provisioning creates, in order:

1. The oracle's account and DID document. The DID carries the oracle's Ed25519 UCAN signing key; the signing mnemonic is stored PIN-encrypted in the oracle's Matrix account room, where the runtime reads it.
2. The oracle's Matrix bot account and account room.
3. The entity (profile, services, parent protocol, linked accounts), its domain card, its Agent Card, its AuthZ config and its P-256 key-agreement key.

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

qiforge-cli new --no-interactive \
  --name my-oracle \
  --network devnet \
  --description "What this oracle does" \
  --org "My Org" \
  --pin 123456 \
  --install

Scaffold only — no login, nothing on chain or on Matrix:

qiforge-cli new --no-interactive --name my-oracle --network devnet --skip-entity

Flags:

In non-interactive mode no Agent Card is published; publish one later with qiforge-cli agent-card.

After new, add your OPEN_ROUTER_API_KEY to .dev.vars and run pnpm dev (wrangler dev, both scripts, on http://localhost:8787). See What qiforge-cli new writes.

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-workers and writes the plugin there. A project on the deprecated Node runtime (@ixo/oracle-runtime) is refused.

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 subclass with a manifest stub + one sample tool (climate_echo)
├── climate.plugin.test.ts     # 3 tests, run inside workerd by `pnpm test`
├── fixtures/                  # placeholder for fixtures
└── README-climate.md          # the manifest mirrored as docs

Register the plugin in src/index.ts (plugins: [...BUNDLED_WORKERS_PLUGINS, new ClimatePlugin()]). Name validation: kebab-case, and it must not collide with a plugin the runtime ships.

qiforge-cli create-entity

Provisions an oracle — entity, DID with its Ed25519 UCAN signing key, Matrix account and account room, domain card, P-256 key — without scaffolding a project. new runs the same flow. It prints the oracle's credentials once; save them.

qiforge-cli create-entity --no-interactive \
  --network devnet \
  --oracle-name "My Oracle" \
  --org-name "My Org" \
  --description "Oracle description" \
  --api-url https://my-oracle.example.workers.dev \
  --pin 123456

Flags:

qiforge-cli update-entity

Updates an existing entity — for example, adds a controller. Accepts account DIDs as controllers (in addition to entity DIDs).

qiforge-cli update-entity

qiforge-cli update-oracle-api-url

Replaces the URL the oracle entity advertises (its #api and #ws services). The prompt defaults to http://localhost:8787, the wrangler dev address; after deploying, set the Worker's URL (for example https://my-oracle.<subdomain>.workers.dev).

qiforge-cli update-oracle-api-url

qiforge-cli agent-card

Authors an Agent Card (name, description, version, priced services), validates it against the eval engine's schema, uploads it with the oracle's Matrix account and anchors it on the entity — replacing an existing card in one transaction. A local copy is saved as agent-card.json in the project.

qiforge-cli agent-card
qiforge-cli agent-card --no-interactive --card card.json --env oracle-credentials.env

Flags:

qiforge-cli setup-signing-key

The Workers runtime signs every call it makes to IXO services (the user's owner copy in the VFS, the memory engine, the sandbox) with an Ed25519 key, and those services verify it against the oracle's DID document. Oracles created with qiforge-cli 2.0.0 or later get the key at creation. Older oracles carry only secp256k1 keys — the Node runtime used to add the Ed25519 key on its first boot; the Workers runtime only reads it — so they cannot sign UCAN invocations until you run this command.

qiforge-cli setup-signing-key --env oracle-credentials.env

It reads the signing mnemonic from the oracle's account room (or creates it there, PIN-encrypted) and adds its public key to the oracle's DID document with MsgAddVerification, signed and paid for by the oracle's own account. It needs no user login and is idempotent. A Node-era .env with SECP_MNEMONIC, MATRIX_VALUE_PIN, MATRIX_ACCOUNT_ROOM_ID and the bot's credentials works as --env too. Redeploy (or restart) the oracle afterwards.

Flags: --env (otherwise prompted), --network, --no-interactive (requires --env).

qiforge-cli setup-encryption-key

Adds the P-256 keyAgreement key the runtime uses to decrypt per-room secrets: it generates the key pair, stores it PIN-encrypted in the oracle's account room and publishes the public key on the entity. new and create-entity already do this; run it for an oracle that lacks the key. It does not provision the UCAN signing key — that is setup-signing-key.

qiforge-cli setup-encryption-key --env oracle-credentials.env

--env supplies the oracle's Matrix account; without it the command prompts for the account room, the bot's user id and its password. It always prompts for the entity DID and the PIN.

qiforge-cli dashboard-access

Links an oracle to a developer console account: mints a short-lived UCAN invocation with the oracle's signing key and asks the eval engine to link the oracle's entity to your console account DID. Optionally authorizes that account to fund the oracle's performance deposits.

qiforge-cli dashboard-access
qiforge-cli dashboard-access --no-interactive \
  --grant did:ixo:ixo1... --entity-did did:ixo:entity:... --env oracle-credentials.env

Flags: --env (SECP_MNEMONIC, MATRIX_VALUE_PIN and the Matrix credentials), --grant, --entity-did, --grant-deposit, --network, --no-interactive (requires --grant, --entity-did and --env).

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; put the key in .dev.vars (COMPOSIO_API_KEY) and upload it with wrangler secret put. new mints one for you when it can.

qiforge-cli create-composio-key

qiforge-cli create-user

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

qiforge-cli create-user

qiforge-cli logout

qiforge-cli logout

Clears stored authentication. Future commands prompt for auth again.

What qiforge-cli new writes

my-oracle/
├── src/
│   ├── index.ts              # createOracleWorker({ config, plugins }) + export { UserOracleDO, MatrixGatewayDO }
│   ├── gateway.ts            # createGatewayWorker() — the Matrix gateway as its own Worker script
│   ├── config.ts             # identity + prompt slots
│   ├── config.test.ts        # the composed system prompt carries those slots
│   └── plugins/              # your plugins go here
├── test/                     # the Worker the unit tests run in (workerd)
├── .claude/
│   └── skills/qiforge-oracle/  # Claude Code skill (project-local)
├── wrangler.jsonc            # oracle script: vars, Durable Objects, rate limit, crons, aliases, minify
├── wrangler.gateway.jsonc    # gateway script
├── .dev.vars                 # the Worker's secrets for wrangler dev (gitignored)
├── .dev.vars.example
├── oracle-credentials.env    # the oracle's wallet mnemonic + Matrix credentials (gitignored; back it up)
├── agent-card.json           # local copy of the published Agent Card
├── package.json
├── pnpm-workspace.yaml       # yjs and langsmith overrides, build-script policy
├── tsconfig.json
├── vitest.config.ts
├── README.md
└── CLAUDE.md                 # bootstrapping for Claude Code

• The runtime. package.json pins @ixo/oracle-runtime-workers to exactly 0.37.0 (the release with the long-thread isolate-memory fixes) and @ixo/matrix-bot-workers-sdk to the exact version that release depends on. A newer runtime reaches scaffolds through a CLI release.
• Two Worker scripts. The oracle script holds the HTTP shell and one Durable Object per user; the gateway script holds only the Matrix bot, so the two never share an isolate's 128 MB heap. pnpm run deploy deploys the gateway, then the oracle.
• Wrangler configs. Both set "minify": true — keep it on (see deploy → Cloudflare Workers runtime) — plus nodejs_compat, the @matrix-org/matrix-sdk-crypto-wasm and jsdom aliases, and limits.cpu_ms: 300000. After provisioning, vars hold the oracle's DIDs, Matrix user and account room and the network's service URLs.
• Secrets. .dev.vars holds MATRIX_ORACLE_ADMIN_PASSWORD, MATRIX_RECOVERY_PHRASE, MATRIX_VALUE_PIN, an empty OPEN_ROUTER_API_KEY and, when one was minted, COMPOSIO_API_KEY. Upload them for a deployment with wrangler secret bulk .dev.vars (oracle script) and wrangler secret put … -c wrangler.gateway.jsonc for the three Matrix secrets.
• Credentials. oracle-credentials.env is the operator's record — wallet mnemonic, signing mnemonic, Matrix password, PIN. The Worker never reads it; agent-card, setup-signing-key, setup-encryption-key and dashboard-access take it with --env.

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.) has dense guidance on the Workers runtime — adding plugins and tools, env vars and secrets, the bundled plugins, testing inside workerd, local dev and deploy. The skill is project-local: it ships inside every scaffolded oracle. See the skill source in the CLI repo.

Related references

• Identity and auth guide — what create-entity, setup-signing-key and setup-encryption-key set up.
• Deploy — wrangler, secrets and the isolate memory limits.
• Environment variables — what goes in the wrangler vars and .dev.vars.
• CLI source — every command's implementation.