CLI reference

The Agentknock CLI pairs a client with your phone, requests secrets for commands, and uploads existing secrets for review. This reference describes command behavior and configuration. For installation and your first use, see Install the CLI and Getting started.

Run a command

Select each secret with -s and put the command after --:

agentknock -s github -- gh repo view

Here, github is the secret name. The equivalent explicit form is agentknock run -s github -- gh repo view.

See agentknock run for environment-variable delivery, SSH authentication, and Git signing.

Pairing commands

Command	Purpose
agentknock pairing status	Read the local pairing state.
agentknock pairing start	Begin a pairing and display its verification code.
agentknock pairing finish	Activate a pairing accepted on the phone.
agentknock pairing abort	Discard a pending pairing.
agentknock pairing remove	Remove an active pairing.

Secret commands

Command	Purpose
agentknock secret list	List available secrets without revealing their values.
agentknock secret upload	Send secret data to the phone for review.

The pairing and secret groups require a subcommand. Running commands and listing or uploading secrets requires an active pairing.

Help and version

Use --help for detailed help or -h for a shorter summary. Both work at the top level and on individual commands:

agentknock --help
agentknock secret upload --help

--version and -V print the installed version. Help and version requests do not require pairing or a connection to the relay.

Running agentknock, agentknock pairing, or agentknock secret without the required arguments displays help on standard error and exits with 2. An explicit help request exits successfully.

All command-line arguments must be valid UTF-8. The options for run, including --reason, --quiet, and --verbose, apply only to running a command; they are not global options for pairing or secret management.

Output and waiting

Agentknock separates command results from progress and errors:

Output	Destination
Pairing status, verification codes, and pairing or upload success messages	Standard output, as text.
secret list results	Standard output, as JSON.
Explicit help and version requests	Standard output.
Progress and errors	Standard error.

For run and its shorthand form, every line of Agentknock’s own runtime messages begins with AGENTKNOCK: followed by a space. The launched command’s output is unchanged, so the prefix helps distinguish Agentknock’s messages in a terminal or combined log. This also applies to later SSH authentication and Git signing messages. Help, argument errors, and the pairing and secret commands use ordinary CLI formatting without the prefix.

Commands launched with run inherit standard output and standard error. --quiet suppresses Agentknock’s runtime messages, including errors, while preserving the command’s own output. See Output and errors for redirection and exit-status behavior.

While waiting for the phone, Agentknock reports the current stage and total elapsed time every 30 seconds. The stage distinguishes waiting for delivery from waiting for a response. Approval settings can handle a request automatically, but the phone still needs to be online to respond.

Agentknock reconnects and resumes an exchange after temporary connection failures. It stops retrying after 10 consecutive failures or when a series of failures reaches roughly two minutes. Successful communication resets those limits. These are connection-recovery limits: there is no fixed CLI deadline for a phone response while the relay connection stays healthy. A request can still end if the device or relay rejects or expires it.

Interrupting a command stops the local operation. It can leave work already received or completed on the phone; the individual command pages explain how to check the result before retrying.

An error labeled an unauthenticated error report comes from the relay without confirmation from the phone. It doesn’t establish whether the phone approved, denied, or completed the request. Agentknock reports it without automatically discarding the local pairing; check the phone when the outcome is uncertain.

Exit status

Before a requested command starts, Agentknock uses these exit codes:

Code	Meaning
0	The CLI operation completed successfully.
1	The operation failed, including a denied request, invalid local state, a connection failure, or failure to start the command.
2	The command line is invalid, such as a missing argument or conflicting options.

Once run launches its command, that command replaces Agentknock and determines the exit status. For example, a tool that exits with 2 then reports its own failure, not an Agentknock argument error.

Success describes the requested operation: pairing status succeeds even when it reports no pairing, and a successful upload confirms receipt rather than acceptance of the secret.

Local state

The CLI stores one pending or active pairing in pairing.json inside its Agentknock directory. Commands using the same Agentknock directory share that pairing.

The directory is selected in this order:

1. --agentknock-home PATH: a global option available on all commands. The path must be nonempty; relative paths are resolved against the current working directory.
2. AGENTKNOCK_HOME: a nonempty absolute directory path.
3. $HOME/.agentknock: the default when neither override is set. HOME is required only for this default.

The selected path must be valid UTF-8. Use the same directory for pairing and subsequent commands. For example:

agentknock --agentknock-home /persist/agentknock pairing status

The option does not change HOME or AGENTKNOCK_HOME in a launched command’s environment.

The file contains the client’s identity and authentication material, but no delivered secret values. Agentknock creates it with permissions 0600: read and write access for the owner only. It refuses to read the file with different permissions. Normal requests can update the pairing’s authentication state, so the state directory must remain writable. Use the pairing commands to manage it.

Configure a relay proxy

The CLI connects to relay.agentknock.dev over a secure WebSocket on port 443. It uses the following environment variables to select a proxy; it does not read the operating system’s proxy settings.

Variable	Purpose
https_proxy or HTTPS_PROXY	Use this proxy for the secure WebSocket connection.
all_proxy or ALL_PROXY	Use this proxy when an HTTPS-specific proxy is not set.
no_proxy or NO_PROXY	Connect directly to matching destinations.

Empty values are skipped. Within each pair, a nonempty lowercase value takes precedence over the uppercase value. An HTTPS-specific setting takes precedence over an all-protocol setting. An invalid selected value causes an error; Agentknock does not try another setting or connect directly instead. HTTP_PROXY and http_proxy do not apply to the secure relay connection.

Proxy URLs support http:// and https://; a proxy address without a scheme uses HTTP. HTTP Basic authentication can be supplied as user:password@host. The proxy must support HTTP CONNECT tunneling, and an HTTPS proxy also needs a valid TLS certificate. SOCKS proxies are not supported.

NO_PROXY is a comma-separated list of destinations to reach directly. A domain matches itself and its subdomains, with or without a leading dot; * bypasses the proxy for every destination. Matching uses the destination hostname, so use relay.agentknock.dev to bypass the relay proxy. Do not include a URL scheme or port. The selected proxy URL is validated even when NO_PROXY bypasses it.

For example:

HTTPS_PROXY=http://proxy.example:8080 agentknock secret list

These settings control Agentknock’s relay connection. A launched command inherits the environment and applies its own proxy rules to its connections.