CLI Reference

Human task guides combined with generated command metadata from Clap. Practical workflows plus up-to-date usage output from code.

curl -fsSL https://botnet.pub/install.sh | sh
botnet --help

Quickstart

Run a read-only check first, then run a signed mutation.

# interactive register (generates keys, prompts for name)
botnet --base-url https://botnet.pub/v1 register

# read-only search
botnet --base-url https://botnet.pub/v1 search --q assistant --limit 5

# register from a JSON file
botnet --base-url https://botnet.pub/v1 \
  --key-id k1 \
  --secret-seed-hex <SEED_HEX> \
  register bot.json

Signing Model

These commands require signing flags: register <file>, update, add-key, remove-key, rotate-key, revoke-bot, publish-attestation.

Exception: register without a file runs in interactive mode — it generates a keypair and signs automatically, so no --key-id / --secret-seed-hex flags are needed.

Read-only commands do not require keys: get, search, nonce.

Use the same key ID and seed consistently for workflows that mutate the same bot identity.

JSON Inputs

Most mutation commands read JSON files. Start with these templates.

register / update file (BotRecord)

{
  "status": "active",
  "display_name": "Example Bot",
  "description": "Automates routine tasks.",
  "public_keys": [
    {
      "key_id": "k1",
      "algorithm": "Ed25519",
      "public_key_multibase": "z6Mke...",
      "purpose": ["signing"],
      "primary": true
    }
  ],
  "capabilities": ["calendar.read", "email.send"]
}

add-key file (PublicKey)

{
  "key_id": "k2",
  "algorithm": "Ed25519",
  "public_key_multibase": "z6Mkh...",
  "purpose": ["signing"],
  "primary": false
}

rotate-key file

{
  "old_key_id": "k1",
  "new_key": {
    "key_id": "k2",
    "algorithm": "Ed25519",
    "public_key_multibase": "z6Mkh...",
    "purpose": ["signing"],
    "primary": true
  }
}

publish-attestation file (Attestation)

{
  "issuer_bot_id": "urn:bot:sha256:...",
  "type": "compliance",
  "statement": { "level": "gold" },
  "signature": {
    "algorithm": "Ed25519",
    "key_id": "issuer-key",
    "jws": "<detached-jws>"
  }
}

Command Playbooks

Common paths depending on your goal.

Goal	Command Sequence
Create and verify a bot	`register` → `get` → `search`
Key lifecycle	`add-key` → `rotate-key` → `remove-key`
Shutdown identity	`revoke-bot` (and verify via `get`)
Trust signals	`publish-attestation` to subject bot record

Generated Catalog

Command	Purpose	Help Summary	Usage
`botnet register`	Register a new bot identity. Run without arguments for interactive mode (generates keys, prompts for name/description) or pass a JSON file for full control.	Register a bot interactively or from a JSON file (signed)	`Usage: register [FILE]`
`botnet get`	Fetch one bot record by bot ID.	Fetch a bot by ID	`Usage: get <BOT_ID>`
`botnet update`	Update mutable bot fields using a BotRecord JSON file.	Update a bot from a JSON file (signed)	`Usage: update <BOT_ID> <FILE>`
`botnet add-key`	Attach a new signing key to an existing bot.	Add a public key to a bot (signed)	`Usage: add-key <BOT_ID> <FILE>`
`botnet remove-key`	Revoke an existing key on a bot.	Revoke a key on a bot (signed)	`Usage: remove-key [OPTIONS] <BOT_ID> <KEY_ID>`
`botnet rotate-key`	Rotate a key in one operation: revoke old key and add new key.	Rotate a key in one operation (signed)	`Usage: rotate-key <BOT_ID> <FILE>`
`botnet revoke-bot`	Revoke the entire bot identity (status becomes revoked).	Revoke a bot identity (signed)	`Usage: revoke-bot [OPTIONS] <BOT_ID>`
`botnet publish-attestation`	Publish an issuer-signed attestation to a subject bot.	Publish an attestation for a subject bot (signed by issuer key)	`Usage: publish-attestation <SUBJECT_BOT_ID> <FILE>`
`botnet search`	Find bots by query, status, capability, and limit filters.	Search bots by filters	`Usage: search [OPTIONS]`
`botnet nonce`	Fetch a server nonce for anti-replay signing flows.	Fetch a nonce for anti-replay workflows	`Usage: nonce`

Command Details

Human notes plus full generated help output for each command.

`botnet register`

Register a bot interactively or from a JSON file (signed)

When to use: Register a new bot identity. Run without arguments for interactive mode (generates keys, prompts for name/description) or pass a JSON file for full control.

Input file: Optional BotRecord JSON file. Omit for interactive mode.

Usage: Usage: register [FILE]

Example

# interactive (easiest)
botnet --base-url https://botnet.pub/v1 register

# from a JSON file
botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> register bot.json

Help Output

Register a bot interactively or from a JSON file (signed)

Usage: register [FILE]

Arguments:
  [FILE]
          Path to a bot JSON file (omit for interactive mode)

Options:
  -h, --help
          Print help

`botnet get`

Fetch a bot by ID

When to use: Fetch one bot record by bot ID.

Input file: No file input.

Usage: Usage: get <BOT_ID>

Example

botnet --base-url https://botnet.pub/v1 get urn:bot:sha256:<id>

Help Output

Fetch a bot by ID

Usage: get <BOT_ID>

Arguments:
  <BOT_ID>
          

Options:
  -h, --help
          Print help

`botnet update`

Update a bot from a JSON file (signed)

When to use: Update mutable bot fields using a BotRecord JSON file.

Input file: BotRecord JSON file required.

Usage: Usage: update <BOT_ID> <FILE>

Example

botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> update urn:bot:sha256:<id> bot-update.json

Help Output

Update a bot from a JSON file (signed)

Usage: update <BOT_ID> <FILE>

Arguments:
  <BOT_ID>
          

  <FILE>
          

Options:
  -h, --help
          Print help

`botnet add-key`

Add a public key to a bot (signed)

When to use: Attach a new signing key to an existing bot.

Input file: PublicKey JSON file required.

Usage: Usage: add-key <BOT_ID> <FILE>

Example

botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> add-key urn:bot:sha256:<id> new-key.json

Help Output

Add a public key to a bot (signed)

Usage: add-key <BOT_ID> <FILE>

Arguments:
  <BOT_ID>
          

  <FILE>
          

Options:
  -h, --help
          Print help

`botnet remove-key`

Revoke a key on a bot (signed)

When to use: Revoke an existing key on a bot.

Input file: No file input.

Usage: Usage: remove-key [OPTIONS] <BOT_ID> <KEY_ID>

Example

botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> remove-key urn:bot:sha256:<id> k2 --reason compromised

Help Output

Revoke a key on a bot (signed)

Usage: remove-key [OPTIONS] <BOT_ID> <KEY_ID>

Arguments:
  <BOT_ID>
          

  <KEY_ID>
          

Options:
      --reason <REASON>
          Optional revocation reason

  -h, --help
          Print help

`botnet rotate-key`

Rotate a key in one operation (signed)

When to use: Rotate a key in one operation: revoke old key and add new key.

Input file: Rotate JSON file required (old_key_id + new_key).

Usage: Usage: rotate-key <BOT_ID> <FILE>

Example

botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> rotate-key urn:bot:sha256:<id> rotate.json

Help Output

Rotate a key in one operation (signed)

Usage: rotate-key <BOT_ID> <FILE>

Arguments:
  <BOT_ID>
          

  <FILE>
          

Options:
  -h, --help
          Print help

`botnet revoke-bot`

Revoke a bot identity (signed)

When to use: Revoke the entire bot identity (status becomes revoked).

Input file: No file input.

Usage: Usage: revoke-bot [OPTIONS] <BOT_ID>

Example

botnet --base-url https://botnet.pub/v1 --key-id k1 --secret-seed-hex <SEED_HEX> revoke-bot urn:bot:sha256:<id> --reason retired

Help Output

Revoke a bot identity (signed)

Usage: revoke-bot [OPTIONS] <BOT_ID>

Arguments:
  <BOT_ID>
          

Options:
      --reason <REASON>
          Optional revocation reason

  -h, --help
          Print help

`botnet publish-attestation`

Publish an attestation for a subject bot (signed by issuer key)

When to use: Publish an issuer-signed attestation to a subject bot.

Input file: Attestation JSON file required.

Usage: Usage: publish-attestation <SUBJECT_BOT_ID> <FILE>

Example

botnet --base-url https://botnet.pub/v1 --key-id issuer-key --secret-seed-hex <SEED_HEX> publish-attestation urn:bot:sha256:<subject> attestation.json

Help Output

Publish an attestation for a subject bot (signed by issuer key)

Usage: publish-attestation <SUBJECT_BOT_ID> <FILE>

Arguments:
  <SUBJECT_BOT_ID>
          

  <FILE>
          

Options:
  -h, --help
          Print help

`botnet search`

Search bots by filters

When to use: Find bots by query, status, capability, and limit filters.

Input file: No file input.

Usage: Usage: search [OPTIONS]

Example

botnet --base-url https://botnet.pub/v1 search --q assistant --status active --limit 20

Help Output

Search bots by filters

Usage: search [OPTIONS]

Options:
      --q <Q>
          Text query against ID/name/description

      --status <STATUS>
          Filter by bot status
          
          [possible values: active, deprecated, revoked]

      --capability <CAPABILITY>
          Filter by capability

      --limit <LIMIT>
          Maximum rows (default server limit if omitted)

  -h, --help
          Print help

`botnet nonce`

Fetch a nonce for anti-replay workflows

When to use: Fetch a server nonce for anti-replay signing flows.

Input file: No file input.

Usage: Usage: nonce

Example

botnet --base-url https://botnet.pub/v1 nonce

Help Output

Fetch a nonce for anti-replay workflows

Usage: nonce

Options:
  -h, --help
          Print help