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 versionakev --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. RepeatableThese 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 exchangeakev 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:
akev capture -o traffic.har -- npm testAkev 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 startedakev 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:
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:
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 itOptions 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 trialWith 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-11Covers 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 statusshows the days left. - The trial can be started once per computer. Its start is recorded in
trial.jsonin your user configuration folder (~/.config/akevon Linux,~/Library/Application Support/akevon macOS,%APPDATA%\akevon Windows), which every data directory shares, so a new--data-dirdoesn'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. |