Creating an API Token and Connecting with the CLI

How to generate the first API token and connect to Wiretastix with wiretastix-cli, locally or remotely.

Every other CLI-based how-to in this documentation assumes you’re already connected with wiretastix-cli. This guide covers the one thing that has to happen before any of that: getting your first API token, and pointing the CLI at the daemon – whether it’s running on the same machine or a remote host.

1. Generate the First Token

There’s no default token, and no CLI command can create the first one – wiretastix-cli needs a token to connect at all. Instead, run the daemon binary itself with --initialize:

sudo wiretastix-daemon --initialize -c /etc/wiretastix/wiretastix.yaml

This is a one-off command, not a way to start the daemon – it creates a single token named primaryToken, prints it once, and exits immediately without starting the API/web servers. A few things worth knowing about it:

It only works once. If any token already exists, it refuses to run at all: you can't initialize an initialized system. It’s for bootstrapping, not routine use.
--wipe (--initialize --wipe) deletes every existing token first, then creates one new one. Reach for this only if you’ve lost all access and need a hard reset – it invalidates every token currently in use, not just one.
Save the printed token now. Like everything else token-related in Wiretastix, it’s shown exactly once and stored hashed afterward – there’s no way to retrieve it again. If you lose it, create an additional one with the CLI’s own token create command instead (see the CLI Commands Reference) once you have any working token to connect with.

2. Connect with the CLI

wiretastix-cli is an interactive shell – launching it always drops you into a > prompt. It needs two things to connect: the API URL and the token. Either pass them as flags:

wiretastix-cli --api https://127.0.0.1:8095/wiretastix/api/v1/ --token YOUR_TOKEN

or set them as environment variables first, which avoids leaving the token sitting in your shell history or visible to anyone listing processes:

export WIRETASTIX_API="https://127.0.0.1:8095/wiretastix/api/v1/"
export WIRETASTIX_TOKEN="YOUR_TOKEN"
wiretastix-cli

Either way, you land in the interactive shell and can start typing commands (peer list, user list, and so on).

3. Connecting from a Remote Host

By default, apiserver.binding in wiretastix.yaml is 127.0.0.1:8095 – the API only listens on localhost, so the CLI (and its default --api value) only works when run on the same machine as the daemon.

To connect from another host, an administrator needs to change that binding first:

apiserver:
    binding: 0.0.0.0:8095   # or a specific reachable IP instead of 0.0.0.0
    base: /wiretastix/api/v1/

…then restart the daemon. From the remote machine, point the CLI at that address instead of 127.0.0.1:

export WIRETASTIX_API="https://vpn.example.com:8095/wiretastix/api/v1/"
export WIRETASTIX_TOKEN="YOUR_TOKEN"
wiretastix-cli

Make sure the port is reachable through any firewall/security group between you and the server – see Network Firewall (NFTables) if Wiretastix’s own firewall integration is involved.

4. About That Certificate Warning

The API server always presents a self-signed certificate – generated fresh at startup, valid for 10 years, with no configuration option to give it a real one instead. This is expected, not a sign anything is wrong. Your CLI (or curl, or anything else) will refuse it by default with a “certificate signed by unknown authority” style error unless you tell it not to validate:

wiretastix-cli -k

The -k (insecure) flag skips certificate validation for the connection. It does not mean the traffic is unencrypted – the self-signed certificate still encrypts everything on the wire with the same TLS as a “real” one would. What it skips is verifying the server’s identity against a certificate authority, which is a different property.

Why This Is Fine by Default

apiserver.binding defaults to 127.0.0.1:8095 – localhost only. Nothing leaves the machine, so there’s no third party on the network path who could be impersonating the server in the first place. Using -k here is normal, by-design behavior, not a shortcut around a real security gap.

Why It Stops Being Fine Once You Expose It

The moment you rebind the API to a public or even just a private/internal IP (as in Section 3), that assumption no longer holds – now there’s a real network between the CLI and the daemon, and it’s worth taking the exposure seriously. The API will still use the same self-signed certificate either way – that part doesn’t change and isn’t itself a problem, encryption still works fine. What changes is that you now need to actually think about who can reach that port and how.

If You Want a “Real” Certificate

If you’re assigning the API a DNS name and exposing it properly, you can put a reverse proxy (nginx, Caddy, Traefik) in front of it and terminate TLS there with a real certificate (e.g., via Let’s Encrypt) – see Reverse Proxy Setup, which already covers proxying the API specifically. But doing that is really a decision to expose this interface properly, and it comes with more homework than just swapping a certificate: IP allowlisting, restricting which endpoints are reachable, tighter token hygiene, and everything else in Security Best Practices’s API access control section – not just TLS.

In practice, a CA-signed certificate on its own buys you very little here. This is a bearer-token-authenticated admin API, not a service the general public connects to without prior knowledge – you already know the address you’re pointing the CLI at, and the token is what actually gates access, not certificate trust. Encryption-in-transit is the part that matters, and the self-signed certificate already provides it. A real certificate becomes worthwhile once you’re behind a proper reverse-proxy setup with its own hardening – not as a fix on its own.