#Command line

klens (also installed as kopialens-cli) runs KopiaLens from a terminal, for scripts and AI agents. It talks to a running KopiaLens through its API, with an API token.

#Where to find it

• Windows installer: keep Add the klens command line to PATH ticked during setup (it's on by default). Then klens works in any new terminal. To install without it, run the installer with /NOPATH.
• Portable copy: run bin\klens.exe from the KopiaLens folder.
• Docker: docker exec <container> klens status.
• Any other computer with Python 3: download klens.py from the release and run python klens.py --url http://<kopialens-address>:7123 status.

#Sign in once

Create a token in Settings → API tokens, then:

klens login

Paste the token when asked. klens checks it and keeps it in Windows Credential Manager (the Keychain on macOS, a private file in your user folder on Linux). klens logout forgets it.

Instead of logging in, a script can set KOPIALENS_TOKEN, or pass --token. To reach another KopiaLens, use --url or set KOPIALENS_URL. klens --url ... login remembers that address. Options like --url, --token and --table go before the command name.

#Commands

Command	What it does
klens status	KopiaLens version, repositories and backups
klens repos	The connected repositories and their numbers
klens sources 1	The backed-up folders in repository 1
klens search 1 "*.iso" --largest	Search the files in the backups
klens file 1 <source> <path>	One file: sizes, versions, and what removing it frees
klens folder 1 <path> / klens ls 1 <path>	A folder's totals, or its contents
klens snapshots 1	A repository's snapshots
klens index 1	Index status. Add --build to start an index run
klens snapshot 1 <source>	Take a snapshot now
klens plan 1 --prefix <path>	Preview removing files. Prints a plan id
klens dry-run 1 <plan>	Ask kopia what the plan would remove
klens run 1 <plan> --yes	Remove the plan's files
klens delete-snapshots 1 <id>... --dry-run	Preview deleting snapshots. --yes deletes them
klens jobs / klens job <id> --wait	Recent jobs, or follow one to its end
klens logs --level warning	The KopiaLens log
klens approval <id>	The status of an approval request
klens docs / klens docs cli	The list of docs pages, or one page
klens api GET /api/repos	Call any API route (--data for a JSON body, --query key=value)

Run klens <command> --help for every option. Replies are JSON. klens --table jobs prints a table instead. Progress and waiting messages go to the error output, so the JSON stays clean.

#Removing files

Removing is always plan, dry run, then run:

klens plan 1 --prefix "D:/Old projects"
klens dry-run 1 <plan>
klens run 1 <plan> --yes

The plan lists the files and sizes, and is valid for one hour. run removes exactly what the plan showed. It needs a Full Access token and your approval in KopiaLens.

#Approvals

When a command needs your approval, klens says so and waits:

Waiting for approval in KopiaLens (request 4f2a91c0). Approve or deny it in Settings > API tokens.

Once you approve it, the command carries on by itself. With --no-wait, it prints the request id and stops. Run the same command again with --approval <id> after approving.

#Exit codes

Code	Meaning
0	Done
1	Failed, or the job ended as failed or stopped
2	Wrong use, for example run without --yes
3	Refused or denied: the token's permission, a step a token can never do, or a denied approval
4	Left waiting for approval (--no-wait)

#HTTPS

klens accepts KopiaLens's own certificate on this computer. For another address with a self-signed certificate, add --insecure.