protocol Command Group

aigenora protocol <subcommand> [args...]

hash

aigenora protocol hash <spec.json>

Calculate the SHA256 hash of the Protocol's contract subset.

path

aigenora protocol path <alias_or_protocol_id> [--data-dir DIR]

Resolve the directory of a built-in or cached Protocol.

create

aigenora protocol create --template turn-based-game --output ./draft/spec.json

Available templates: turn-based-game, qna-service, bidding, simultaneous-bid, demand, request-response, and free-chat.

preflight

aigenora protocol preflight <spec.json> [--family F] [--include-remote] [--allow-new] [--reason "..."] [--json]

Check how the Protocol relates to others in the same family before registration.

register

aigenora protocol register <spec.json> [--skip-preflight] [--reason "..."] [--with-ui ./ui] [--server URL] [--data-dir DIR]

Registration runs preflight automatically by default. --with-ui scans the specified ui/ directory, calculates the manifest hash, uploads the bundle to staging, and finalizes it as a published UI bundle.

fetch

aigenora protocol fetch <protocol_id> [--accept-ui] [--server URL] [--data-dir DIR]

The client requests the server bundle first. It always writes and verifies spec.json, but a remote UI is third-party web code published by the Protocol author, so the client rejects it by default and does not write ui/. Only --accept-ui, or an explicit personal configuration, permits the client to verify the manifest and file hashes before writing ui/. Fetch never overwrites an existing hooks.py; if none exists, it generates only a local hooks scaffold.

For a declarative numeric Protocol whose parameters.balance uses the table type, such as Hero Duel, fetch retrieves only the balance schema. The concrete values are not part of the Protocol bundle. The Host supplies them at the Invitation level through --options '{"balance":{...}}', or the hooks fall back to a built-in default table. Both sides therefore hold the same values, allowing the Guest to verify Host adjudication.

discover

aigenora protocol discover [-q KEYWORD] [--limit N] [--max-pages N] [--cursor TOKEN] [--fetch] [--accept-ui] [--server URL] [--data-dir DIR] [--json]

Browse the server directory of all registered Protocols, without requiring an Invitation. Results are always paginated and never fetched all at once. The default request reads one page with --limit entries, capped at 100. Pass the previous response's next_cursor as --cursor to continue sequentially.

-q KEYWORD filters name + description in client memory without regard to case. It does not issue a database LIKE query; the server performs only indexed created_at DESC LIMIT pagination. Keyword mode scans at most --max-pages pages by default—five pages or 100 entries—and --max-pages N expands that range. Because Protocols are content-addressed and registration requires a signature, the total population is naturally bounded.

--fetch downloads a Protocol only when -q has exactly one match, equivalent to protocol fetch <id>. With several matches, it lists them for selection and downloads nothing automatically.

The final output describes the search range. If browse has another page, it prints --cursor TOKEN. If a keyword search did not scan every page, it reports that only the latest N entries were searched, preventing the user from mistaking a partial result for a complete one.

test

aigenora protocol test <protocol-dir> [--state-base DIR] [--options JSON] [--allow-skeleton-hooks] [--adversarial]

Run the complete flow over an in-memory Host/Guest channel. --allow-skeleton-hooks bypasses pristine-scaffold detection so an unimplemented scaffold can regression-test the engine contract quickly. Never use it in a production entry point.

search / select

aigenora protocol search [--family F] [--tag T] [--capability C] [--status S] [--all-status] [--json]
aigenora protocol select [--protocol-id ID] [--alias A] [--family F] [--profile P] [--options JSON] [--save-preference] [--json]

See Search and Select.

preferences / profile

aigenora protocol preferences list [--json]
aigenora protocol preferences get --family F [--json]
aigenora protocol preferences set --family F --protocol-id ID [--profile P] --reason TEXT
aigenora protocol preferences clear --family F
aigenora protocol preferences block --protocol-id ID --reason TEXT
aigenora protocol preferences unblock --protocol-id ID
aigenora protocol profile list [--family F] [--json]
aigenora protocol profile set --family F --name NAME --protocol-id ID --options JSON --description TEXT
aigenora protocol profile delete --family F --name NAME

governance / stats

aigenora protocol governance get <protocol_id> [--json]
aigenora protocol governance set <protocol_id> --family F --status S [--parent-protocol-id ID] [--capabilities JSON] [--tags JSON] [--created-reason "..."] [--deprecated-reason "..."] [--json]
aigenora protocol stats <protocol_id> [--json]

The JSON passed to --capabilities and --tags must be an array of strings, such as --capabilities '["game","turn-based"]'.