Commands reference

Every subcommand the otigen binary exposes — what it does, what it accepts, what it prints. For the formal contract on flag values, exit codes, and event streams, see OTIGEN_BINARY_SPEC.md. (The spec is the authoritative source; where this chapter and the spec disagree, the binary's --help output is the runtime truth and the spec is the one being chased.)

Global flags apply to every subcommand:

Path defaults that say <config-dir>/... are resolved against the parent of --config, not the cwd. Invocations from outside the project tree therefore find / write bundles next to the project.

otigen new

Scaffold a single contract. By default it's a minimal counter; --from <template> clones a canonical example instead. Run inside a workspace to add the contract as a new member (see otigen init and Workspaces).

otigen new [OPTIONS] [NAME]
otigen new --list           # show the template catalog

otigen new --list
otigen new my-counter --from counter
otigen new my-token --from erc20-token --dir ./projects/my-token

The scaffold is a full single-contract project tree (Cargo.toml, otigen.toml, src/, tests/, Makefile). Run from inside a workspace, otigen new <name> instead scaffolds the contract under contracts/<name>/ and registers it in the root manifest's [workspace].members + order.

otigen init

Scaffold a new multi-contract workspace — a project that groups several contracts which build, test, and deploy together. See Workspaces for the full flow.

otigen init [OPTIONS] [NAME]

otigen init my-app --lang rust
otigen init my-parachain --lang go --type parachain
otigen init my-c-app --lang c --dir ~/projects/my-c-app

The workspace root gets a [workspace] otigen.toml, a .gitignore, a README.md, and a Makefile. The first member — a minimal counter (increment + get) with 3 behaviour tests — lands at contracts/counter/. Add more with otigen new <name> from the root; run otigen test immediately to confirm the toolchain is wired.

otigen check

Validate the project without packaging. Fast alternative to otigen build for pre-commit hooks and IDE integrations.

otigen check [OPTIONS]

Runs the otigen.toml parser + WASM validator + ABI extractor. Skips the bundle write. Typical latency on a small contract: tens of milliseconds.

otigen check
otigen check --no-compile

otigen build

Validate + package the compiled .wasm into a deploy bundle.

otigen build [OPTIONS]

At a workspace root, otigen build builds every member into the shared artifacts/ directory (and prunes bundles for removed members); --contract <name> scopes to one. See Workspaces.

Output bundle lands at --out (default <config-dir>/artifacts/<name>.bundle/) with:

• contract.wasm — the compiled binary (blake3-checksummed).
• abi.json — the contract's ABI extracted from [functions.*].
• manifest.json — canonical manifest snapshot (build-deterministic apart from a build_timestamp field).
• metadata.json — JSON-extracted [metadata] section (the project's source URL, license, description). Hashed into manifest.metadata_hash_blake3 for explorer verification.
• otigen.toml — the source manifest copied verbatim so otigen deploy / verify / test can re-read declarations from a bundle without the source tree.

Exits non-zero on validation failure (VALIDATION_FAILURE = 1). Scripts can rely on the exit code.

otigen build
otigen build --json              # NDJSON event stream for CI
otigen build --no-compile        # repackage existing wasm

otigen test

Run contract behaviour tests declared in tests/*.test.toml.

otigen test [OPTIONS]

At a workspace root, otigen test builds + tests every member (a member with no test file is skipped, not failed) and prints a workspace summary; --contract <name> scopes to one. --watch isn't supported at the workspace level. See Workspaces.

Verbosity is the standard global -v flag, repeated for more detail:

otigen test                # default — per-test pass/fail + duration
otigen test -v             # + INFO logs
otigen test -vv            # + DEBUG (host-fn calls, slot derivations)
otigen test --json         # NDJSON event stream

For per-call assertions + storage-diff rendering, declare them in [tests.expect] / expect.* in the test TOML; failures print the expected-vs-actual. See OTIGEN_TEST_SPEC.md for the test DSL.

otigen wallet

Manage FALCON-512 signing accounts in ~/.pyde/keystore.json.

otigen wallet <ACTION> [OPTIONS]

Subactions: new, import, list, show, delete, password, export, sign, verify.

wallet new

Create a fresh keypair, prompt for a password, encrypt + store.

otigen wallet new [NAME] [--password-stdin]

[NAME] is positional and optional — omitted prompts on a TTY (errors under --json or piped stdin). --password-stdin reads the encryption password from stdin (two consecutive lines — password + confirmation — or a single line treated as both).

otigen wallet new deployer
printf 'pw\npw\n' | otigen wallet new alice --password-stdin

wallet import

Import an existing keypair into the keystore. Three modes:

otigen wallet import [NAME]                              # interactive: paste pubkey + secret key
otigen wallet import --from-file <PATH> <NAME>           # restore a wallet export
otigen wallet import --from-devnet [--prefix <P>] [--count <N>] [--password-stdin]

printf 'pw\npw\n' | otigen wallet import --from-devnet --password-stdin
otigen wallet import --from-file ./alice.backup.json alice

wallet list

otigen wallet list

Print every account name + address in the keystore. Touches no encrypted material.

wallet show

otigen wallet show <NAME>

Print one account's address + public key. No password needed.

wallet delete

otigen wallet delete <NAME> [--yes]

Remove an account. Asks for confirmation (re-type the account name) unless --yes.

wallet password

otigen wallet password <NAME>

Re-encrypt the account under a new password. The keypair itself is unchanged. Password rotation requires a real PTY today — no --password-stdin on this subcommand yet.

wallet export

otigen wallet export <NAME> [--out <PATH>]

Export the account as a portable encrypted backup. Same Argon2id + AES-256-GCM ciphertext as the in-keystore entry; the original password decrypts it. No password prompt — the export ciphers-as-is. Restore later with wallet import --from-file.

otigen wallet export alice --out ./alice.backup.json
otigen wallet export alice > ./alice.backup.json

wallet sign

FALCON-512 sign arbitrary message bytes. For off-chain attestations / signing challenges. Don't use for chain transactions — deploy / upgrade / call sign the canonical Poseidon2 tx hash, which is what the chain verifier expects.

otigen wallet sign [OPTIONS] --message <MESSAGE> [NAME]

otigen wallet sign devnet-0 --message "hello world"
otigen wallet sign devnet-0 --message 0xdeadbeef --hex --password-stdin <<< pw

wallet verify

Verify a signature against a message + public key. Exit code is the verdict: 0 on valid, 1 on invalid.

otigen wallet verify [OPTIONS] [NAME] --message <MSG> --signature <HEX>

otigen wallet verify devnet-0 --message "hello world" --signature 0x...
otigen wallet verify --pubkey 0x09... --message 0xdeadbeef --hex --signature 0x...

otigen deploy

Sign and submit a deploy transaction.

otigen deploy [OPTIONS]

Receipt poll timeout is 60 s (constant, not CLI-configurable). On success the contract address appears in the receipt; the CLI prints it.

otigen deploy --from devnet-0 --password-stdin <<< pw
otigen deploy --from devnet-0 \
              --rpc-url http://127.0.0.1:29933 \
              --chain-id 31337 \
              --password-stdin <<< pw
otigen deploy --dry-run     # print wire bytes, don't submit

There is no --gas-limit / --gas-price flag today; values come from [deploy] in otigen.toml (gas_limit = 10_000_000, gas_price = "auto").

At a workspace root, otigen deploy prints a deploy plan (network, RPC, account, order), builds every member, then deploys each member in [workspace].order — resolving @name cross-references to deployed addresses, skipping members already registered on-chain, and caching addresses to artifacts/deployments/<network>.json. Constructor args come from [workspace.args]; with --contract <name> they may instead be given on the command line (positional or --args 0x<hex>, overriding that member's [workspace.args] entry — positional @name values still resolve), and --value funds that one member's constructor. --dry-run prints the plan and each member's resolved args without building, submitting, unlocking the wallet, or touching the RPC. See Workspaces.

otigen addresses

List a workspace's deployed member addresses, read from the deploy cache (artifacts/deployments/<network>.json) written by otigen deploy. Workspace-only — a single contract's address is printed by otigen deploy.

otigen addresses [OPTIONS]

Every workspace member is listed with its deployed address, or (not deployed) if it hasn't been deployed to the selected network. --json emits the raw name → address map for scripts.

otigen addresses
otigen addresses --network testnet
otigen addresses --json

otigen upgrade

Replace a contract's WASM via the upgrade flow (spec §3.4).

Status (v1): The chain has no TxType::Lifecycle handler yet. The CLI refuses to submit by default (EngineNotReady). See Lifecycle for the v1 proxy-pattern alternative and the --i-know-engine-rejects bypass.

otigen upgrade [OPTIONS] <TARGET>

otigen pause / unpause / kill

Lifecycle controls (spec §3.5). Same EngineNotReady gate as upgrade.

otigen pause   [OPTIONS] <TARGET>
otigen unpause [OPTIONS] <TARGET>
otigen kill    [OPTIONS] <TARGET> [--yes]

All three share the same flag surface as upgrade:

otigen pause   my-counter --from devnet-0 --i-know-engine-rejects --password-stdin <<< pw
otigen unpause my-counter --from devnet-0 --i-know-engine-rejects --password-stdin <<< pw
otigen kill    my-counter --from devnet-0 --i-know-engine-rejects --yes --password-stdin <<< pw

otigen call

Invoke a function on a deployed contract. View vs mutating is decided by the presence of --from: with a signing wallet the call submits a tx; without one it runs in view mode via pyde_call.

otigen call [OPTIONS] <TARGET> <FUNCTION> [ARGS...]

Typed arguments

Positional ARGS are marshalled per [functions.<fn>].inputs in declaration order. Per type:

• Primitives (u8..u128, i8..i128, bool, address, hash32, bytes, string) — bare values. address-typed inputs accept either a 0x-prefixed 64-char hex literal OR a wallet name from the local keystore (devnet-0, alice, …) — wallet names resolve to the keystore entry's address.
• vec(T) — JSON array literal: '[1,2,3]' (standard borsh Vec<T> wire shape).
• Struct from [types.<Name>] — JSON5 object literal: '{maker:devnet-0,amount:100,paid:false}'. Field order does not matter; the marshaller looks fields up by name.
• Enum from [types.<Name>] — variant name as a bare string: Pending. v1 enums are unit-only.
• Unquoted 0x hex literals of 16+ chars are auto-quoted before JSON5 parse, so 32-byte hash + address values don't need surrounding quotes inside struct + array literals.

# View mode (free, no tx, no gas, no signing):
otigen call my-counter get
otigen call my-token balance_of devnet-0          # wallet-name address
otigen call my-token balance_of 0x9b8c...         # explicit hex address
otigen call my-pool   echo_amounts '[100,200,300]'

# Struct + enum
otigen call my-orders create '{maker:devnet-0,amount:100,paid:false}'
otigen call my-orders set_status Active

# Raw hex view return (default decodes)
otigen call my-token balance_of devnet-0 --raw    # 0x40420f00000000000000000000000000

# Mutating mode (signed tx):
otigen call my-counter increment --from devnet-0 --password-stdin <<< pw
otigen call my-token   transfer 0x9b8c... 1000 --from devnet-0 --password-stdin <<< pw
otigen call my-token   transfer devnet-1 1000  --from devnet-0 --password-stdin <<< pw

# Escape hatch — pre-encoded calldata when no local otigen.toml is available
otigen call my-contract some_fn --args 0x0100000000000000

Auto-decoded view returns

By default, view-call returns are decoded per [functions.<fn>].outputs:

• Single output → bare value (1000000 for a uint128).
• Multi-output → tuple syntax ((true, 1000000)).
• Compound shapes (vec(T), struct(<Name>), enum) → JSON5-style.

--raw preserves the on-wire hex — useful for piping into external decoders or for contracts the CLI doesn't have an outputs schema for. In --json mode the call_result event carries return_data (raw hex) alongside a separate decoded field with the decoded form (see crates/otigen-cli/src/commands/call.rs for the exact event shape).

Mutating calls decode too

A write function that returns data (pyde::return) shows it the same way — the payload rides the tx receipt's return_data and is decoded per the declared outputs:

  ✓ Call succeeded.
  Return:   2

In --json mode the call_included event carries the return_data hex. The console's tx command prints the raw hex.

Reverts show the author's message

A revert — view or tx — prints the string the contract passed to pyde::revert, never a wasm backtrace:

otigen [ERROR] Reverted: erc721: nonexistent token

This works across call, deploy (constructor reverts included), send, and the console.

otigen send

Native PYDE transfer between accounts. The simplest tx the chain processes — TxType::Standard against a recipient with no data, the cheapest gas budget the engine accepts (MIN_GAS_LIMIT = 21000).

otigen send [OPTIONS] <RECIPIENT> <AMOUNT>

otigen send devnet-1 100_000_000 --from devnet-0 --password-stdin <<< pw
otigen send 0xabc... 0x5f5e100  --from devnet-0 --password-stdin <<< pw
otigen send devnet-1 100 --from devnet-0 \
            --rpc-url http://127.0.0.1:29933 --chain-id 31337 \
            --password-stdin <<< pw

otigen inspect

Read contract / account metadata + storage (spec §3.6).

otigen inspect [OPTIONS] <TARGET>

Default mode prints the account snapshot: address, account type, balance, nonce, code hash, code size, state root. --state-field / --field short-circuit to a single-slot read.

otigen inspect 0xabc...                            # full account snapshot
otigen inspect 0xabc... --state-field counter      # substrate field
otigen inspect 0xabc... --field counter            # legacy raw-slot field
otigen inspect my-token --rpc-url https://rpc.example

otigen verify

Verify that a deployed contract's bytes match a local bundle (spec §3.9).

otigen verify [OPTIONS] <TARGET>

otigen verify 0xabc...
otigen verify 0xabc... --bundle ./snapshot/my-token.bundle
otigen verify 0xabc... --explorer https://explorer.pyde.network --api-key-env PYDE_EXPLORER_KEY
otigen verify 0xabc... --strict-toolchain

otigen devnet

Run a local devnet. The chain runtime is embedded in the otigen binary — no separate pyde download. Single validator, deterministic genesis pre-fund, Ctrl-C for graceful shutdown.

otigen devnet [OPTIONS]

On startup, devnet auto-imports devnet-0..devnet-9 into the local keystore with password "devnet" so otigen deploy --from devnet-0 works without a separate wallet import --from-devnet step. Pass --no-auto-import-wallets to skip this when running against a populated keystore or in CI.

otigen devnet --rpc-listen 127.0.0.1:9933
otigen devnet --rpc-listen 127.0.0.1:9933 --tick-ms 500
otigen devnet --fork ./snapshot.borsh --rpc-listen 127.0.0.1:9934

Validator + full-node roles still ship via the engine's own pyde binary — operator concerns, not author concerns.

otigen console

Interactive REPL against a Pyde node (spec §3.8).

otigen console [OPTIONS]

Drops into a pyde> prompt with line editing and persistent history. The MVP surface today:

Addresses accept either 0x... hex or registered names (resolved via pyde_resolveName).

otigen console --network devnet --from devnet-0

otigen validator

Read-only queries over the chain-side validator registry.

otigen validator <ACTION> [OPTIONS]

Exits non-zero with NotAValidator for unregistered addresses so scripts can branch on exit code without parsing stdout.

otigen validator show 0xabc...
otigen validator by-operator 0xdef...

Registration / stake / unbond / unjail flows live on the engine's pyde binary — those are tx submission, not introspection.

otigen update

Pull the latest release and replace the binary. Wraps the canonical curl install one-liner so you don't have to copy the URL each time.

otigen update [OPTIONS]

otigen update                          # latest
otigen update --version v0.1.0-alpha.3 # pin a tag
otigen update --check                  # poll without side effect

Under the hood: curl -fsSL <install-url> | bash -s -- <flags>. Same URL the installation page documents; otigen update is just sugar so the flow stays inside the CLI.