This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Xodbox CLI

Xodbox CLI Reference

Synopsis

A network interaction listening post.

  • Quickly determine if an application interacts with network services.
  • Easily create custom responses to interaction requests.

Options

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
  -h, --help            help for xodbox
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

1 - Completion

Generate completion script

Synopsis

To load completions:

Bash:

source <(xodbox completion bash)

# To load completions for each session, execute once:
# Linux:
xodbox completion bash > /etc/bash_completion.d/xodbox
# macOS:
xodbox completion bash > /usr/local/etc/bash_completion.d/xodbox

Zsh:

# If shell completion is not already enabled in your environment,
# you will need to enable it.  You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc

# To load completions for each session, execute once:
xodbox completion zsh > "${fpath[1]}/_xodbox"

# You will need to start a new shell for this setup to take effect.

fish:

xodbox completion fish | source

# To load completions for each session, execute once:
xodbox completion fish > ~/.config/fish/completions/xodbox.fish

PowerShell:

xodbox completion powershell | Out-String | Invoke-Expression

# To load completions for every new session, run:
xodbox completion powershell > xodbox.ps1
# and source this file from your PowerShell profile.

xodbox completion [bash|zsh|fish|powershell]

Options

  -h, --help   help for completion

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox - A network interaction listening post
Auto generated by spf13/cobra on 16-Jul-2026

2 - Config

Manage the xodbox config file.

Synopsis

View, validate, and edit the xodbox config file.

Running ‘xodbox config’ with no subcommand prints the currently loaded config. Use a subcommand for specific operations.

xodbox config [flags]

Options

  -e, --embedded   Print the embedded config file
  -h, --help       help for config

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

3 - Config Get

Get a config value by dot-notation path

Synopsis

Query a specific value from the config file using a dot-notation path.

xodbox config get <path> [flags]

Examples

  xodbox config get defaults.server_name
  xodbox config get handlers.0.listener
  xodbox config get notifiers.0.notifier

Options

  -h, --help   help for get

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

4 - Config Init

Write the default config file to disk

Synopsis

Write the embedded default config to the –config path (default xodbox.yaml). Refuses to overwrite unless –force is set.

xodbox config init [flags]

Options

      --force   Overwrite existing config file
  -h, --help    help for init

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

5 - Config Set

Set a config value by dot-notation path

Synopsis

Set a specific value in the config file and save it. The config is validated before writing; invalid configs are rejected.

Send SIGHUP to the running xodbox process to reload without a full restart.

xodbox config set <path> <value> [flags]

Examples

  xodbox config set defaults.server_name MyServer
  xodbox config set handlers.0.listener :8080
  xodbox config set notifiers.0.filter "^HTTP"

Options

  -h, --help   help for set

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

6 - Config Validate

Validate the config file

Synopsis

Load the config file and check that all handler, notifier, and worker names are valid. Exit code 1 on validation failure.

xodbox config validate [flags]

Options

  -h, --help   help for validate

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

7 - Interactions

Inspect and prune recorded interactions.

Synopsis

Manage the interactions the listeners have recorded. Use ‘purge’ to remove noise from a known source (e.g. a leftover beacon from an old test) that has been flooding the database.

Options

  -h, --help   help for interactions

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

8 - Interactions Purge

Delete recorded interactions matching a source, target, or handler.

Synopsis

Delete interactions matching the given filters (ANDed together). At least one filter is required so the whole table isn’t wiped by mistake. Pair this with the ignore_cidrs / ignore_pattern config defaults to stop the same noisy callout from being recorded going forward.

Examples: xodbox interactions purge –remote 203.0.113.7 xodbox interactions purge –remote 10.0.0.0/8 –dry-run xodbox interactions purge –target /old-test-callback –handler httpx

xodbox interactions purge [flags]

Options

      --dry-run          report how many rows match without deleting
      --handler string   restrict to a single handler (e.g. httpx, dns)
  -h, --help             help for purge
      --remote strings   source IP or CIDR to purge (repeatable, comma-separated)
      --target string    substring matched against the request target (HTTP path / DNS qname)

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

9 - Payload

Manage payloads.

Synopsis

Manage payloads served by xodbox. Use subcommands to inspect or export payload data.

Options

  -h, --help   help for payload

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

10 - Payload Dump

Dump payloads.

Synopsis

Dump all payloads from the database as YAML.

xodbox payload dump [flags]

Options

  -h, --help   help for dump

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

11 - Serve

Start xodbox server.

Synopsis

Start the xodbox server with all configured handlers and notifiers.

Loads the config file, opens the database, seeds initial state, and starts each handler in its own goroutine. Shuts down gracefully on SIGINT/SIGTERM.

xodbox serve [flags]

Options

  -h, --help   help for serve

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox - A network interaction listening post
Auto generated by spf13/cobra on 16-Jul-2026

12 - Sink

Manage interaction sinks (named/described slugs).

Synopsis

Create and manage sinks: named, described slugs you embed in payloads to correlate out-of-band interactions. View a sink’s hits in the admin web UI.

Options

  -h, --help   help for sink

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

13 - Sink Add

Create a sink; generates a random slug when none is given.
xodbox sink add [slug] [flags]

Options

      --description string   what this sink is for (shown in the UI and CLI list)
  -h, --help                 help for add
      --notify               send notifications when this sink is hit

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox sink - Manage interaction sinks (named/described slugs).
Auto generated by spf13/cobra on 16-Jul-2026

14 - Sink List

List sinks and their hit counts.
xodbox sink list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox sink - Manage interaction sinks (named/described slugs).
Auto generated by spf13/cobra on 16-Jul-2026

15 - Sink Rm

Delete a sink (its captured interactions are left untouched).
xodbox sink rm <slug> [flags]

Options

  -h, --help   help for rm

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox sink - Manage interaction sinks (named/described slugs).
Auto generated by spf13/cobra on 16-Jul-2026

16 - Update

Update xodbox to latest version

Synopsis

Update or check for updates. The default update method is to download the latest release from GitHub.

xodbox update [flags]

Examples

# Update to latest version
xodbox update

# Use go install to update
xodbox update -g

# Download from a specific URL
# Not sure why anyone else would need this. I use it for quickly testing builds on different machines.
xodbox update -u http://10.0.0.2:8000/dist/xodbox_darwin_arm64/xodbox

# This is typically used after I run the following:
#	goreleaser release --clean --snapshot
#	python -m http.server

Options

  -C, --check        Check for update
  -f, --force        Force update, even if release is not newer
  -g, --go-install   Use go install instead of downloading release from GitHub
  -h, --help         help for update
  -u, --url string   URL to download from (force implies)

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

  • xodbox - A network interaction listening post
Auto generated by spf13/cobra on 16-Jul-2026

17 - User

Manage admin console users.

Synopsis

Create and manage the users that can log into the embedded admin web UI.

Options

  -h, --help   help for user

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

18 - User Add

Create an admin console user (bootstrap the first admin).
xodbox user add <username> [flags]

Options

      --admin             grant the admin role
  -h, --help              help for add
      --password string   use this password instead of a generated one

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

19 - User List

List admin console users.
xodbox user list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

20 - User Passwd

Reset a user’s password (revokes their active sessions).
xodbox user passwd <username> [flags]

Options

  -h, --help              help for passwd
      --password string   use this password instead of a generated one

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026

21 - User Rm

Delete a user and their API keys and sessions.
xodbox user rm <username> [flags]

Options

  -h, --help   help for rm

Options inherited from parent commands

      --config string   Config file path (default "xodbox.yaml")
      --debug           Debug mode
      --reset-db        Reset database

SEE ALSO

Auto generated by spf13/cobra on 16-Jul-2026