Advanced CLI and API Usage

Explore advanced features of the Wiretastix CLI and direct API interaction.

Beyond basic commands, the wiretastix-cli offers a few connection conveniences, and the underlying RESTful API allows for direct programmatic control of Wiretastix.

Advanced CLI Usage

There Is No Non-Interactive Mode

wiretastix-cli is always an interactive shell. Running it – with or without extra flags or trailing words – always launches the > prompt; any commands you want to run are typed there, one at a time. There is no way to pass a command on the invocation line and have it execute directly for scripting or automation. If you need to automate against Wiretastix, use the REST API directly instead.

Environment Variables

For convenience and security (avoiding tokens in shell history), it’s recommended to set the API URL and token as environment variables:

export WIRETASTIX_API="https://127.0.0.1:8095/wiretastix/api/v1/"
export WIRETASTIX_TOKEN="YOUR_API_TOKEN"

# Now you can launch the shell without passing --api/--token
wiretastix-cli
> peer list

Insecure TLS Connections

If your Wiretastix daemon uses self-signed TLS certificates and you need to connect from the CLI without strict certificate validation (e.g., for testing or internal networks), use the -k (insecure) flag:

wiretastix-cli -k

Warning: Using -k in production environments is not recommended as it bypasses critical security checks.

Showing Version Information

The -V flag requires the same --api/--token (or environment variables) as any other invocation – it does not skip connection setup, and it does not exit early. It only changes the format of one line printed at startup; the shell still launches afterwards.

wiretastix-cli -V

Once inside, running version at the prompt does the same thing on demand, without needing to relaunch:

> version

Direct API Interaction

The Wiretastix daemon exposes a RESTful API that you can interact with using any HTTP client (e.g., curl, Postman, or a programming language’s HTTP library). This is ideal for integrating Wiretastix into custom applications or automation workflows, and it’s the only way to automate Wiretastix without a human typing into the interactive CLI.

Authentication

All API requests require authentication using the API token. The token must be sent in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_TOKEN

Example: Listing Peers with `curl`

Assuming your API is accessible at https://127.0.0.1:8095/wiretastix/api/v1/ and you have your YOUR_API_TOKEN:

curl -k -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://127.0.0.1:8095/wiretastix/api/v1/peers/

The -k flag is used here because the example assumes a self-signed certificate. Remove it if you have a valid, trusted TLS certificate.

Example: Creating a Peer with `curl`

curl -k -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-peer-from-api"}' \
  https://127.0.0.1:8095/wiretastix/api/v1/peers/

This always creates an unmanaged peer with no user association – the POST /peers/ endpoint only binds a name field; there is no user_id (or any other) parameter that attaches it to a user. The only way a peer gets created with a user association is through that user’s own OIDC self-service login flow; it isn’t something the CLI, this endpoint, or any other API call can do on a user’s behalf.

API Endpoints

Refer to the API Endpoints Reference for a complete list of available endpoints and their expected request/response formats.