QiForge CLI

A command-line interface for creating and managing IXO Oracle projects. This CLI helps you set up AI Agent oracles built with LangGraph, using Matrix as a datastore with linked resources stored on the IXO blockchain.

What is QiForge CLI?

The QiForge CLI automates the complete setup of AI Agent oracle projects. It handles:

• Blockchain Integration: Creates entities on the IXO blockchain with linked resources stored in Matrix
• Matrix Account Creation: Sets up Matrix accounts for data storage and communication
• Project Initialization: Clones the QiForge boilerplate and configures the environment
• Authentication: Supports two modes — SignX (QR code via IXO Mobile App) or offline wallet (local mnemonic)
• Non-interactive Mode: Full CI/CD support with --no-interactive flag and CLI flags for all parameters

Prerequisites

• Node.js 22+
• IXO Mobile App (for SignX authentication) or a mnemonic phrase (for offline mode)

Installation

Install the CLI globally using npm:

npm install -g qiforge-cli

Or with pnpm:

pnpm add -g qiforge-cli

Important for pnpm users: After installation, you need to approve build scripts:

pnpm approve-builds -g

When prompted, select protobufjs and approve it:

✔ Choose which packages to build · protobufjs
✔ The next packages will now be built: protobufjs.
Do you approve? (y/N) · true

Or with yarn:

yarn global add qiforge-cli

Quick Start

1. Initialize a new oracle project:

   qiforge-cli --init

2. Or run the interactive CLI:

   qiforge-cli

3. Follow the prompts:

   • Choose authentication: SignX (QR code) or Offline (local mnemonic)
   • Enter your project name
   • Select the template (QiForge boilerplate or custom)
   • Configure your oracle details (name, profile, LLM model, prompts, etc.)

Authentication

The CLI supports two authentication modes:

SignX (Default)

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

qiforge-cli
# Select "SignX Wallet (QR code with mobile app)" when prompted

Offline Wallet

Uses a local mnemonic phrase for authentication. No mobile app needed.

# Interactive
qiforge-cli offline-login

# Non-interactive (CI/CD)
qiforge-cli offline-login --network devnet --mnemonic "your twelve word mnemonic phrase here" --matrixPassword "your-matrix-password"

Offline login flags:

| Flag | Description | | ------------------ | ------------------------------------------------ | | --network | Network to use (devnet, testnet, mainnet) | | --mnemonic | Mnemonic phrase for wallet derivation | | --matrixPassword | Matrix account password | | --name | Display name (falls back to Matrix profile name) |

Commands

qiforge-cli --init - Initialize Project

Creates a new IXO Oracle project with all necessary components:

• Project Setup: Creates directory and clones the QiForge boilerplate
• Entity Creation: Creates a blockchain entity with linked resources stored in Matrix
• Matrix Account: Sets up Matrix account for data storage
• Oracle Config: Saves oracle.config.json with oracle metadata, LLM model, and prompt settings
• Environment Configuration: Creates .env file with all necessary variables

qiforge-cli - Interactive Menu

Launches an interactive menu with the following options:

• init - Initialize a new project
• create-entity - Create a blockchain entity
• chat - Chat with the oracle
• logout - Sign out

Other Commands

| Command | Description | | -------------------- | -------------------------------------------------------- | | create-entity | Create an entity with oracle profile, linked resources | | chat | Chat with the oracle | | offline-login | Login with a local mnemonic (offline wallet) | | logout | Clear your authentication session | | --help, -h | Show help information and available commands |

Non-interactive Mode (CI/CD)

Both init and create-entity support a --no-interactive flag for fully automated pipelines. All parameters can be passed as CLI flags.

Init (non-interactive)

qiforge-cli --init --no-interactive \
  --name my-oracle-project \
  --network devnet \
  --oracle-name "My Oracle" \
  --price 100 \
  --api-url http://localhost:4000 \
  --pin 123456

Init flags:

| Flag | Description | Default | | -------------- | ----------------------------------------------- | -------------------------------------- | | --name | Project name (required in non-interactive mode) | — | | --path | Project directory path | ./<name> | | --repo | Template repository URL | [email protected]:ixoworld/qiforge.git | | --force | Overwrite existing directory | false |

Create Entity (non-interactive)

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

| Flag | Description | Default | | ----------------------- | ------------------------------------------------- | --------------------------------- | | --network | Network (devnet, testnet, mainnet) | devnet | | --oracle-name | Oracle name | My oracle | | --price | Price in IXO credits | 100 | | --org-name | Organization name | IXO | | --logo | Logo URL | Auto-generated from oracle name | | --cover-image | Cover image URL | Same as logo | | --location | Location string | New York, NY | | --description | Entity description | Default placeholder | | --website | Website URL (optional) | — | | --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 if not provided | | --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 of MCP servers ([{"url":"..."}]) | — |

Oracle Configuration

After entity creation, the CLI saves an oracle.config.json file in your project root (and apps/app/) with oracle metadata:

{
  "oracleName": "My Oracle",
  "orgName": "IXO",
  "description": "Oracle description",
  "location": "New York, NY",
  "website": "",
  "price": 100,
  "apiUrl": "http://localhost:4000",
  "network": "devnet",
  "entityDid": "did:ixo:entity:...",
  "logo": "https://...",
  "prompt": {
    "opening": "Welcome! I can help you with...",
    "communicationStyle": "Friendly and concise",
    "capabilities": "I can search the web, manage tasks..."
  },
  "model": "moonshotai/kimi-k2.5",
  "skills": [],
  "customSkills": [],
  "mcpServers": []
}

Supported LLM Models

During interactive entity creation, you can choose from:

• moonshotai/kimi-k2.5 (default)
• anthropic/claude-sonnet-4
• openai/gpt-4o
• google/gemini-2.5-pro
• meta-llama/llama-4-maverick
• Or enter a custom model identifier

Project Structure

After initialization, your project will have:

your-oracle-project/
├── oracle.config.json        # Oracle configuration
├── apps/
│   └── app/
│       ├── .env              # Environment configuration
│       ├── oracle.config.json # Copy for Docker builds
│       └── ...               # Application files
├── packages/                 # Shared packages
└── ...                      # Other project files

Environment Configuration

The CLI automatically creates a .env file with:

PORT=4000
ORACLE_NAME=your-oracle-name

# Matrix Configuration
MATRIX_BASE_URL=https://matrix.ixo.world
MATRIX_ORACLE_ADMIN_ACCESS_TOKEN=your-access-token
MATRIX_ORACLE_ADMIN_PASSWORD=your-password
MATRIX_ORACLE_ADMIN_USER_ID=your-user-id

# AI/ML Services (configure as needed)
OPENAI_API_KEY=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_HOST=https://cloud.langfuse.com
OPEN_ROUTER_API_KEY=

# Blockchain Details (store securely)
ORACLE_ADDRESS=your-address
ORACLE_DID=your-did
ORACLE_MNEMONIC=your-mnemonic
MATRIX_VAULT_PIN=your-pin
ENTITY_DID=your-entity-did

Authentication Details

The CLI supports two authentication modes:

• SignX: Keep your IXO Mobile App open during the login process. All transactions require QR code scanning.
• Offline: Uses a local mnemonic phrase. Transactions are signed locally — no mobile app needed. Credentials are stored in ~/.wallet.json.

Your session is persisted locally for future use. Run qiforge-cli logout to clear it.

Next Steps

After project initialization:

1. Navigate to your project:

   cd your-project-name

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm build

4. Start development:

   cd apps/app
   pnpm start:dev

Development (Contributing to CLI)

If you want to contribute to the CLI itself:

1. Clone the repository:

   git clone https://github.com/ixoworld/ixo-oracles-cli
   cd ixo-oracles-cli

2. Install dependencies:

   pnpm install

3. Build the CLI:

   pnpm build

4. Run locally:

   pnpm start

Development Scripts:

• pnpm build - Build the CLI
• pnpm dev - Watch mode for development
• pnpm test - Run tests
• pnpm lint - Lint code
• pnpm type-check - Type check

Support

For issues and questions:

• Create an issue in the repository
• Join the IXO Discord community
• Check the IXO documentation

License

This project is licensed under the Apache License 2.0. See License.txt for details.