CLI Reference

The Mycelium command line tool (`mycelium`) is the core executable utility of the developer toolchain. It manages project scoping, compiles Python contract scripts to WASM, configures encrypted wallet storage, handles ledger deployments, and queries registry records.

mycelium.toml Manifest Configuration

Every Mycelium project requires a manifest file named `mycelium.toml` at its root. The CLI automatically reads parameters from this file to streamline commands, writing back on-chain contract addresses and public keys during deploy actions.

[project]
name    = "my_agent_project"
version = "0.1.0"
author  = "Developer Name <dev@example.com>"

[agent]
framework   = "gemini"             # gemini | anthropic | langgraph | custom
model       = "gemini-2.0-flash"   # Pinned LLM model specifier
unique_name = "oracle_node_alpha"  # Global unique DNS name in the Hive Registry

[onchain]
source_contract   = "contract.py"        # Path to Python contract file
target_wasm       = "build/contract.wasm"# Target compiled WebAssembly file
network           = "testnet"            # testnet | mainnet
contract_id       = "CCW3QNEL..."        # Auto-filled by 'mycelium deploy'
wallet_public_key = "GDA23..."           # Auto-filled by 'mycelium deploy'

[registry]
hive_registry_address = "CCHLAG6L4C6ETKD3ZOYE4GRP3VRUB6A2ES6P52VTENXQURL2VFWXI4XC"
service_endpoint      = "https://agent-api.example.com"
capabilities          = ["price-feed", "usd-xlm"]

Manifest Section Details:

• `[project]`: Metadata containing project naming, versioning constraints, and author specifications.
• `[agent]`: Defines the off-chain runtime properties, including the target AI model framework and the unique registry identity string.
• `[onchain]`: Manages ledger paths, networks, contract address mappings, and public wallet addresses.
• `[registry]`: Specifies the target Hive Registry directory contract address, the agent's external HTTP callback URL, and active service capabilities.

CLI Commands Index

mycelium init

Scaffolds a new agent workspace containing standard template files, including a configuration manifest, a baseline Python contract script, and a runner script. Unless skipped, it launches an interactive wizard prompting for framework selection and model choices.

Scaffold a workspace prompting for inputs:

mycelium init my_new_agent

Scaffold instantly using default settings:

mycelium init my_new_agent --yes

Flags: --yes / --non-interactive (skip interactive setup prompts), --force (overwrite existing directories).

mycelium newwallet

Generates an encrypted Ed25519 cryptographic keypair file at `.mycelium/wallet.json`. The private key is encrypted using AES-256-GCM with a PBKDF2 key derivation algorithm (600,000 iterations, 16-byte random salt). Filesystem permissions are locked down to `0600`.

Prompt interactively for wallet passphrase:

mycelium newwallet

Define passphrase via CLI argument:

mycelium newwallet --passphrase "my-secret-passphrase"

Flags: --passphrase <str> (passphrase string), --force (overwrite existing wallet).

mycelium fund

Requests testnet XLM assets from the Stellar network Friendbot faucet to initialize sequence fees and ledger storage reserves for your account.

mycelium fund

Flags: --address <str> (fund override address), --network <net> (target network), --wallet <path> (wallet path).

mycelium check

Parses the Python contract script AST (Abstract Syntax Tree) to check static types, detect syntax anomalies, and confirm compliance with Soroban execution restrictions.

mycelium check contract.py

mycelium compile

Translates the Python DSL contract code into Soroban-compatible Rust source structures, then compiles it down to a WebAssembly binary. When optimized, it triggers `wasm-opt` to reduce size.

Compile standard contract WASM:

mycelium compile

Compile with optimization flags enabled:

mycelium compile --optimize

Flags: --optimize (optimizes WASM file size), -o <path> / --output <path> (output WASM destination).

mycelium deploy

Uploads the compiled WASM binary to the Stellar ledger, deploys a contract instance, and writes the resulting address and public keys back to `mycelium.toml`. On testnet, it auto-funds empty wallets; on mainnet, it asserts a minimum balance of `5.0 XLM` before submitting.

Deploy using manifest configurations:

mycelium deploy

Deploy targeting specific network and WASM path:

mycelium deploy --network testnet --wasm build/contract.wasm

Flags: --network <net> (testnet/mainnet), --wasm <path> (override WASM target), --wallet <path> (signing wallet path).

mycelium register

Uploads your agent's cryptographic public key, endpoints, and capabilities tags (SHA-256 hashed) to the shared global Hive Registry contract.

mycelium register

Flags: --network <net> (override network), --wallet <path> (override wallet path).

mycelium agent

Loads a specific agent runtime script (e.g. `agent.py`) as a module and runs it, binding the on-chain contract ID into the environment as `MYCELIUM_CONTRACT_ID`. It also loads variables from any sibling `.env` file.

mycelium agent agent.py --contract CCW3QNEL...

Flags: --contract <id> (the on-chain contract ID to bind into environment variables).

mycelium status

Queries public ledger endpoints to display local wallet balance reserves, network passphrase, sequence heights, contract deployment state, and Hive Registry registration details in one dashboard.

mycelium status

Flags: --network <net> (target network), --wallet <path> (wallet path).

mycelium call

Invokes an exported smart contract function directly from your terminal, parsing positional arguments or JSON arguments and mapping them to correct Soroban types.

Submit state-changing transaction (requires signature and fee):

mycelium call increment --send --wallet .mycelium/wallet.json

Invoke view function (free query, no fees):

mycelium call get_count --read-only

Invoke function passing JSON-formatted arguments:

mycelium call reset --args '[100, "GDA2..."]'

Flags: --read-only (view function simulation), --contract <id> (target contract), --network <net> (network selector), --send (sign & submit state-changing tx), --wallet <path> (signing wallet path), --args <json> (JSON-formatted positional arguments array).

mycelium resolve

Performs a lookup on the Hive Registry to resolve the endpoint URL and public key details associated with an agent's registered name.

mycelium resolve oracle_node_alpha

Flags: --network <net> (target network), --registry <id> (override registry address).

mycelium pay

Dispatches a direct, signed payment of XLM from your wallet balance to a target registry agent name or wallet public key.

Pay target agent by unique name:

mycelium pay oracle_node_alpha 10.0

Pay target address directly:

mycelium pay GDA23... 5.5

Flags: --network <net> (target network), --wallet <path> (wallet path).

mycelium agents

Scans and outputs a listing of all active registered agents and metadata profiles present on the Hive Registry via event streaming query filters.

List all active agents:

mycelium agents

Stream new registrations from block height without resolving full metadata profiles:

mycelium agents --start-ledger 4500000 --no-resolve

Flags: --network <net> (override network), --registry <id> (registry override), --start-ledger <num> (earliest ledger sequence to scan), --no-resolve (skip resolving full agent details, faster output).

mycelium events

Streams live on-chain contract events matching filtering criteria, highlighting transaction signatures and events topic hashes.

Stream all events for contract:

mycelium events --contract CCW3QNEL...

Stream contract events and follow live transactions:

mycelium events --contract CCW3QNEL... --follow

Flags: --contract <id> (target contract), --network <net> (target network), --start-ledger <num> (starting sequence), --follow / -f (stream new events interactively).

mycelium run

Starts the off-chain agent listener runtime execution process, allowing the agent to wait for incoming HTTP tasks and dispatch payments. It auto-reads the manifest parameters.

Run agent listener process:

mycelium run

Flags: --contract <id> (target contract ID override).

mycelium test

Runs a dry-run local test validation, simulating all contract methods and transaction loops on a mock environment without consuming network fees. Intercepts all state changes and logs estimated fees.

mycelium test

Flags: --contract <id> (target contract ID override).

mycelium doctor

Validates local developer environments, ensuring that dependencies (`stellar-cli`, Rust compiler targets like `wasm32v1-none`, RPC endpoints) are configured correctly and prints troubleshooting steps.

mycelium doctor

Flags: --network <net> (network to test).