DocsCLI reference

Keep & automate

CLI reference

akev is one binary with the web UI built in. Run akev (or akev start) to start Akev. Most other commands work with the Akev that is already running, the desktop app or akev start.

akev [start]              Start Akev (proxy, API and web UI) and open the UI
akev capture -o FILE      Headless capture for CI; writes a HAR file when it ends
    [-- COMMAND …]        (or runs COMMAND through the proxy and ends when it exits)
akev status [--json]      Show whether Akev is running, and where
akev stop                 Stop the running instance
akev tail                 Follow live traffic, one line per completed exchange
akev export               Export captured traffic as HAR or as an .akev session
akev ca …                 The CA certificate: path, show, export, regenerate
akev intercept …          Launch or configure clients (browsers, terminals, devices…)
akev rules get|set        Read or replace the rule set
akev license …            Akev Pro: status, set, remove, trial
akev mcp                  MCP server over stdio, for AI agents
akev update [--json]      Check whether a newer version is out
akev version [--json]     Print the version

akev --help and akev <command> --help list every option.

Global options

These work with every command.

Option Environment variable Meaning
--data-dir DIR AKEV_DATA_DIR Data directory: CA, settings, rules, licence key, daemon.json. Default ~/.local/share/akev on Linux, ~/Library/Application Support/akev on macOS, %LOCALAPPDATA%\akev on Windows.
--token TOKEN AKEV_TOKEN API token. akev start uses it as its token (random otherwise); other commands authenticate with it.
--url URL AKEV_URL API address of a running Akev, instead of finding it through the data directory. Needs --token unless the data directory has a daemon.json.
--license KEY AKEV_LICENSE Akev Pro licence key for this run, not stored. Used by akev start, akev capture and the instance akev mcp starts.
-v, -vv, -vvv RUST_LOG More logging: info, debug, trace. RUST_LOG overrides.

The CLI finds a running instance through daemon.json in the data directory, which the desktop app and akev start write. Output is coloured only on a terminal; set NO_COLOR to turn colours off.

akev start

akev and akev start are the same command.

akev [start] [options]
    --proxy-port PORT     Proxy port for this run (default from settings, 8000; the next
                          free port if it's busy)
    --proxy-bind ADDR     Proxy bind address for this run (default from settings,
                          127.0.0.1). 0.0.0.0 accepts devices on your network
    --api-port PORT       API and web UI port (default 45456, a random one if it's busy;
                          0 = random)
    --api-bind ADDR       API and web UI bind address (default 127.0.0.1). Other addresses
                          expose the API to the network, over HTTPS with a certificate from
                          Akev's CA (the banner and `akev status` print the https address);
                          a custom --token must then be at least 24 characters
    --no-open             Don't open the UI in a browser
    --allow-origin URL    Allow another browser origin to call the API (e.g. a UI dev
                          server). Repeatable
    --rules FILE          Load rules from a file for this run (Akev or HTTP Toolkit export)
    --ephemeral           Don't read or write settings and rules; use a temporary data
                          directory unless --data-dir is given
    --mcp-allow-launch    Let AI agents (MCP) start arbitrary programs (`electron`)
    --mcp-reveal-secrets  Let AI agents see secrets in captured traffic when they ask
                          (otherwise they see [redacted])
    --mcp-allow-path DIR  A folder AI agents may make Akev read and write files in, besides
                          the data directory's exports folder. Repeatable

These options only go with akev or akev start: akev --no-open status is an error.

If Akev is already running with the same data directory (the desktop app or another akev start), akev opens its UI instead of starting a second instance. --ephemeral always starts a new one.

--proxy-port and --proxy-bind are not saved. Changing only the other field in Settings keeps them, and so does regenerating the CA.

akev start opens the UI through open-ui.html, a private redirect page in the data directory, so the API token never shows up on a command line. Other local users can read command lines. If your browser can't open files there (some snap or flatpak browsers), use the Web UI link that is printed. akev status shows it too.

Akev shuts down cleanly on Ctrl+C, SIGTERM, SIGQUIT and SIGHUP, and on Windows when the console window closes. A clean shutdown restores the system proxy and closes launched browsers and terminals, so closing the terminal window or losing an ssh session is safe. When SIGHUP was ignored at startup (nohup akev start &), Akev keeps running when the terminal closes. A second Ctrl+C during the shutdown forces an immediate exit.

akev capture

akev capture -o FILE [options] [-- COMMAND [ARGS…]]
    -o, --output FILE     HAR file to write when the capture ends (required)
    --duration SECS       Stop after SECS seconds (otherwise at Ctrl+C, or when COMMAND exits)
    --filter QUERY        Only write matching exchanges to the HAR file
    --rules FILE          Apply rules (mocks, rewrites…) while capturing
    --proxy-port PORT     Proxy port (default 8000; the next free port if it's busy;
                          0 = random)
    --api-port PORT       API port (default: random)
    --ca-out FILE         Also write this capture's CA certificate (PEM) to FILE
    -q, --quiet           Don't print a line per exchange

akev capture runs its own headless Akev for CI. It reads and writes no settings or rules, and never checks for updates. The simplest way to use it is to give it the command to run:

bash
akev capture -o traffic.har -- npm test

Akev starts, runs npm test with the proxy and CA environment variables already set (the same ones a Fresh Terminal sets: HTTP_PROXY, HTTPS_PROXY, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE and the rest; see certificates), writes the HAR file when the command exits, and exits with the command's exit status, so a failing test run still fails the CI job. Ctrl+C or --duration stop the command too.

Without a command, it captures until Ctrl+C or --duration. It prints the proxy address, the path of the CA certificate and an export line with HTTP_PROXY, HTTPS_PROXY, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS and REQUESTS_CA_BUNDLE for programs you start yourself.

Either way, each completed exchange is printed as one line, in the same format as akev tail. At the end it writes the HAR file and reports how many exchanges it wrote.

Without --data-dir, each capture uses a temporary data directory with a new CA, so akev ca path doesn't point at it. A command after -- is set up for it already; for anything you start some other way (a container, a browser), write the CA to a file with --ca-out and trust that file, or pass --data-dir to use a CA it already trusts.

For Pro features in CI (script rules, for example), set AKEV_LICENSE. A capture uses a trial that is already running, but can't start one. The filter language is the same as in the UI.

akev status and akev stop

akev status shows the version and process id, the proxy address (and LAN addresses), the Web UI link, the CA certificate's path and expiry, and traffic counts. --json prints the status as JSON, with "running": true or false. It exits with code 1 when Akev isn't running.

akev stop stops the running instance and waits up to 10 seconds for it to exit.

akev tail

akev tail [options]
    -f, --filter QUERY    Only show exchanges matching a filter
    --json                Print each exchange as a JSON line instead of a table row
    --history             Also print exchanges that completed before tail started

akev tail follows the traffic of the running Akev, like tail -f. It prints one line for each exchange when it finishes: answered, failed or aborted. A request still waiting, or paused at a breakpoint, shows up once it finishes. Each exchange is printed once. akev tail stops at Ctrl+C, or when Akev stops.

$ akev tail
▲ akev following http://127.0.0.1:45456 — Ctrl+C to stop
GET     200    85ms https://api.example.com/v1/users
POST    201   142ms https://api.example.com/v1/orders
GET     404    32ms https://api.example.com/v1/users/42
GET     ERR     3ms http://localhost:8443/feed  (connection-refused)
GET     200     2ms https://api.example.com/v1/flags  [mocked]

The columns are method, status, duration and URL. Instead of a status code, the status column shows ERR for a request that failed without a response (the reason follows the URL), TLS for a failed TLS handshake and TUN for a tunnel. [mocked] marks a response from a mock rule. The first line goes to stderr, the exchanges to stdout.

--filter takes the filter language of the Traffic view. Akev evaluates it, so body, header and duration filters work:

bash
akev tail --filter 'status:>=500 host:api.example.com'

--json prints each exchange's summary as one JSON object per line, in the ExchangeSummary shape of the API:

bash
akev tail --json | jq -r '.method + " " + .host + .path'

akev export

akev export --har FILE [--filter QUERY] [--redact]
akev export --session FILE [--filter QUERY] [--redact]

Writes the traffic captured by the running Akev to a file: --har as HAR 1.2, --session as a native .akev session. --filter keeps only matching exchanges. --redact replaces secrets (credential headers and cookies, secret query parameters, tokens in text bodies) with [redacted], for example before you share the file; see redact secrets.

akev ca

akev ca path                   Print the path of the CA certificate (PEM)
akev ca show [--json]          Subject, fingerprints, subject_hash_old and validity
akev ca export FILE [--der]    Write the certificate to FILE as PEM, or DER with --der
akev ca regenerate             Generate a new CA (clients must trust the new one)

These work whether or not Akev is running. When nothing is running and there is no CA yet, they create it. DER (.crt, .cer) suits Android and Windows.

akev intercept

akev intercept list                        Interceptors, and whether each is available or active
akev intercept ID [--options JSON]         Activate one (chrome, fresh-terminal, jvm…)
akev intercept stop ID [--options JSON]    Undo it

Options are specific to each interceptor, for example akev intercept chrome --options '{"url": "https://example.com"}'. For attaching to a running Java app, see Running JVMs.

akev rules

akev rules get [-o FILE]    Print the rule set as JSON, or write it to FILE
akev rules set FILE         Replace the rule set (Akev rules JSON or an HTTP Toolkit export)

akev rules set applies the rules, lists any that have errors and then exits with code 2. See rules.

akev tail, akev export, akev intercept and akev rules need a running Akev. Without one they stop with Akev is not running (start it with akev start).

akev license

akev license status [--json]   Plan, licence details and the date your updates run until
akev license set [KEY]         Verify and store a licence key (read from stdin without KEY,
                               or with -)
akev license remove            Remove the stored key
akev license trial             Start the free 14-day Pro trial

With Akev running, the change applies right away. Otherwise it is written to the data directory and applies at the next start.

akev license set stores the key in license.json in the data directory, not in the settings. To keep the key off the command line, pass it on stdin: akev license set < key.txt. --license and AKEV_LICENSE apply to one run only, for CI and containers. Other local users can read command lines, so prefer the environment variable on shared machines. See licensing.

$ akev license status
● Akev Pro
  Licensed to  Ada Lovelace <ada@example.com>
  License      AKV-1
  Covers       versions released until 2027-11-05
  This build   2026-11-11

Covers is your licence's updates-until date. This build is the release date of the Akev you run: the licence unlocks Pro when this date is on or before Covers (see updates).

akev license trial

akev license trial starts the free 14-day trial of every Pro feature: no card, no account, and nothing is sent anywhere. It does the same as Start 14-day trial in Settings → License.

$ akev license trial
● Akev Pro trial — 14 day(s) left
  This build   2026-11-11
  • The 14 days start now. With Akev running, the Pro features unlock right away; otherwise at the next start. akev license status shows the days left.
  • The trial can be started once per computer. Its start is recorded in trial.json in your user configuration folder (~/.config/akev on Linux, ~/Library/Application Support/akev on macOS, %APPDATA%\akev on Windows), which every data directory shares, so a new --data-dir doesn't start it over.
  • After the trial was used, or when a licence already covers this version, the command fails with The trial was already used on this computer, or a license already covers this version.
  • Ephemeral runs (akev start --ephemeral, akev capture) use a trial that is running but never start one.
  • When the trial ends, a running Akev goes back to Free by itself and keeps everything you set up. See without a licence.

akev mcp

akev mcp [--allow-launch] [--reveal-secrets] [--allow-path DIR]…

An MCP server over stdio for AI agents. It connects to the running Akev, or starts a headless one when none is running; that one stops when the agent's session ends. --allow-launch lets agents use the electron interceptor, which starts any program; --reveal-secrets lets them see secrets in captured traffic when they ask; --allow-path adds a folder they may make Akev read and write files in. These apply only to the headless instance akev mcp starts; for a running one, use akev start --mcp-allow-launch, --mcp-reveal-secrets and --mcp-allow-path. See MCP safety. Client setup: MCP.

akev update

akev update checks whether a newer release of Akev is out: it asks the running Akev (sharing its last result) or, when none runs, fetches the release manifest from GitHub itself. --json prints the result as JSON. It only checks: install the update with the desktop app's Update button, or by hand; see updates.

akev version

akev version prints akev <version>, and --json prints {"name":"akev","version":"<version>"}. akev --version works too.

Exit codes

Code Meaning
0 Success. akev stop also exits with 0 when Akev wasn't running.
1 An error, or akev status when Akev isn't running.
other akev capture -- COMMAND exits with the command's own exit status.
2 Invalid command-line arguments, or akev rules set with rules that have errors.

Type to search guides, the CLI and the API.