lokictl Reference

Synopsis

lokictl is a client for the Lowkey Media Server HTTP API. Every command maps to one or more API calls. Results are written to standard output as JSON. Errors are written to standard error as a single JSON object. Exit codes are stable. The tool is designed to be driven by scripts and AI agents as well as by people.

Global flags must appear before the command name. Flags that follow the command belong to that command. Run lokictl help to print the command table for the installed version.

Installation

The binary ships alongside the server in every release package.

The binary has no runtime dependencies. Copy it anywhere on the PATH. To build from source, run the following from the repository root:

Quick Start

1. Confirm the server is reachable. No credential is required.
   lokictl health
2. Authorize the CLI. This opens a browser page on the server, signs you in if needed, and stores a long-lived API key in the CLI config file.
   lokictl login
   On a machine without a browser, use a password instead:
   lokictl login --password <password> --username <user>
3. Verify the stored credential.
   lokictl whoami
4. List the tasks the server can run, then run one and wait for it.
   lokictl task list -o table
lokictl task show describe
lokictl job run describe --apply missing "D:/photos/2024" --wait --timeout 30m
5. Query the library.
   lokictl media query --tag sunset --exclude-tag blurry
lokictl media visual "a red car in the snow" --limit 20
lokictl db query "SELECT COUNT(*) FROM media"

To use a remote server, set LOKICTL_SERVER or pass --server before login. The stored config then carries both the URL and the key.

Connection

Server URL Resolution

The base URL is resolved from the first source that supplies a value, in this order:

1. --server flag
2. LOKICTL_SERVER environment variable
3. server field in the config file
4. Auto-detected default: http://localhost:<port>

The auto-detected port is LOWKEY_PORT if set, otherwise the port field of the local server's own config.json (in the server data directory), otherwise 10111. A CLI on the same machine as the server therefore follows the server's port without configuration.

The base URL is used verbatim as a prefix. Include the scheme. Do not include a trailing path. A reverse proxy that terminates TLS is supported with an https:// URL.

Config File

lokictl login and lokictl key create --save write a JSON file with two optional fields. The file is created with mode 0600 and its directory with 0700.

Set LOKICTL_CONFIG_DIR to relocate the directory.

The file may be written by hand. Either field may be omitted. A missing file is not an error.

Authentication

Every endpoint except /health requires a credential unless the server has Allow Public Access enabled, in which case read-only endpoints accept anonymous requests. The CLI sends its token as Authorization: Bearer <token> on every request. Two kinds of token are accepted:

API keys are the recommended credential for the CLI. They are tied to a user, named, listable, and individually revocable.

Browser Authorization

The default login is a loopback authorization flow (RFC 8252 with PKCE). The sequence is:

1. The CLI opens a listener on an ephemeral 127.0.0.1 port and generates a random state value and a PKCE code verifier.
2. The CLI opens the system browser at <server>/auth/cli/authorize with the port, state, code challenge, and a key name (lokictl@<hostname>). With --no-browser, the URL is printed instead.
3. If the browser has no server session, the server redirects to /login and back.
4. The server shows an approval page naming the user, the key name, and the loopback port. Approving redirects the browser to http://127.0.0.1:<port>/callback with a one-time code. Denying redirects with error=access_denied.
5. The CLI exchanges the code and its verifier at POST /auth/cli/token. The server mints a new lk_ API key owned by the approving user and returns it.
6. The CLI writes the key and the server URL to the config file and prints the key metadata.

Constraints:

• The browser must run on the same machine as the CLI. The callback is a loopback address. Over SSH, use password login.
• The one-time code expires two minutes after approval. The CLI stops waiting for the browser after three minutes and exits 1 with a hint to use --password.
• The server refuses to authorize the CLI while the temporary admin/admin account is the only user. Complete first-run setup first.
• Each successful login creates a new key. Old keys remain valid until revoked. Use lokictl key list to audit them.

Password Login

Calls POST /auth/login and stores the returned JWT in the config file. JWTs issued to API clients are valid for one year and cannot be revoked individually. A warning is printed if the login succeeded as the temporary default admin, since most endpoints return 403 until a real user exists.

API Keys

The plaintext key is returned once, in the key field of the create response. The server stores only a hash. The list output shows id, owner, name, prefix, creation time, and last-used time.

A key may also be presented in an X-API-Key header. The CLI always uses the Authorization header.

Token Precedence

1. --token flag
2. LOKICTL_TOKEN environment variable
3. token field in the config file
4. No credential. Only /health and, with public access enabled, read-only endpoints succeed.

Authentication Errors

Global Flags

Global flags are recognized only before the command name.

Flags accept both --flag value and --flag=value.

Output Contract

Standard Output

On success, stdout carries exactly one JSON document, pretty-printed with two-space indentation and without HTML escaping. The document is the server response for the primary API call, or a CLI-composed object for commands that make several calls. Commands that await a job print the final job object.

With -o table, an array of objects is printed as TSV: a header row of the first element's keys in order, followed by any additional keys found in later elements sorted alphabetically, then one row per element. Nested values are JSON-encoded inside the cell.

Standard Error

On failure, stderr carries exactly one JSON object on one line:

Usage errors print {"error": "usage: ..."} followed by the command's flag list. Progress output from --follow, --wait, and streamed task logs is also written to stderr as plain lines, so stdout remains parseable.

Exit Codes

Destructive Commands

The following commands exit 2 without contacting the server unless --yes is present:

job clear, media delete, media forget, tag delete, tag unassign-bulk, category delete, workflow delete, deps delete, index delete, index prune.

media cleanup and media thumbnail-cleanup delete data without --yes. Use --dry-run first.

Commands

Each entry lists the command form, its flags, the API endpoint it calls, and the shape of its output. Angle brackets mark required positional arguments; square brackets mark optional ones. Media paths are the absolute paths stored in the library (or s3://bucket/key for object storage roots).

Discovery

login, whoami

See Authentication.

key

job

Flags for job run:

Job object fields: id, command, arguments, input, original_input, state (integer: 0 pending, 1 in progress, 2 completed, 3 cancelled, 4 error, 5 paused), dependencies, workflow_id, created_at, claimed_at, completed_at, errored_at, progress_done, progress_total, output_files, source_files.

task

Each option has name, label, type (string, bool, enum, multi-enum, number), optional choices, default, required, and description. An option named x is passed to job run as --x value, or --x alone for booleans.

workflow

media

Flags for media query:

Query results are objects with path, width, height, elo, battles, and, when a tag predicate drives the query, tagLabel, weight, and timeStamp. When a visual predicate is present the array is ordered by descending score.

Flags for media move:

The move re-points the media row, tag assignments, embeddings, faces, scan markers, and battle log in one transaction. A destination that already belongs to another item returns 409 with the conflicting paths; a move never merges two items.

media cleanup

Runs the cleanup task as a job and streams its log to stderr. The task forgets media whose files no longer exist, removing every tag, embedding, face, and battle row that names them, then sweeps dangling sidecar rows. Files are scanned, then re-verified before deletion. Offline volumes are skipped. The final job object is printed to stdout with the full log in stdout.

media thumbnail-cleanup

Runs the thumbnail-cleanup task as a job. It deletes cached thumbnails that no library still references. Every SQLite database found beside the configured one is treated as a library sharing the cache, so thumbnails owned by a sibling library are kept.

index

db

The server accepts a single SELECT or WITH statement and opens the connection in query_only mode. The response is {columns, rows, row_count, truncated, elapsed_ms} where rows is an array of arrays.

taxonomy, tag, category

--stdin reads one path per line. Blank lines are ignored.

deps

Model ids: wd-eva02-large-tagger-v3, siglip2-base-patch16-224, dinov2-base, yunet, sface, anime-head, ccip, faster-whisper.

config, fs, upload

api

Calls any endpoint with the resolved server URL and credential attached. path is appended to the base URL and may include a query string. --body accepts literal JSON, @file, or - for stdin, and is sent with Content-Type: application/json. A JSON response is pretty-printed; any other body is printed as-is. A non-2xx status exits 1 with the standard error object.

Job Input Syntax

job run joins the task id and every positional argument into one string and sends it as the input field of POST /create. The server splits that string on spaces, honouring double quotes, and interprets it as:

• The first token is the task id.
• The last token is the job's input (a path, URL, or query, depending on the task).
• Everything between is passed to the task as its argument list. Options are --name value or --flag.
• A task with no input takes exactly one token.

The splitter has no escape syntax. A token containing a double quote is rejected. Values with spaces must be quoted at the shell level so they reach the CLI as one argument; the CLI re-quotes them. For values containing quotes or newlines, use --field name=value, which is sent out of band and appended as --name value without passing through the splitter.

Per-item tasks (describe, transcribe, hash, dimensions, autotag, embed, faces, process) accept a directory, a single file, or a SQL query returning paths as the input. Inspect the task's options with task show; the --apply option (missing or all) controls whether items that already have the result are reprocessed.

Workflow DAG Format

workflow create, workflow update, and workflow run-adhoc read a JSON array of task nodes. Each node has the following fields:

A file whose top-level value is an object with a dag key is also accepted, so the output of workflow get can be fed back to workflow create.

Recipes

Run a task and wait for the result

Watch a long job's output live

Forget media that no longer exists

Reclaim thumbnail cache space

Ask the database anything

Search the library four ways

Blended query through raw predicates

Keep the embedding index healthy

Curate tags in bulk

Write metadata directly, or have AI generate it

Files moved on disk

Run a saved workflow

Install a model

CI or automation with a scoped key

Environment Variables

Notes and Limits

• job logs and --follow work only while a job is running. The server streams stdout over SSE and does not persist it, except for the cleanup tasks, whose final job object carries the log.
• db query accepts one SELECT or WITH statement. Rows are capped at 1000 by default and 10000 at most; truncated is true when the cap was hit.
• --arg values are strings. SQLite affinity coerces them for comparisons against numeric columns.
• Job input tokens containing a double quote are rejected. Use --field.
• stats returns {"ready": false} until the server has finished its first library count after startup.
• config set cannot write secrets or storage roots, because config get redacts them and the merge would clear them.
• The CLI sends Accept: application/json so that authentication failures return a 401 JSON body instead of a redirect to the login page.
• The api command does not add a trailing newline to non-JSON bodies.

See Also

• HTTP API Reference
• Job Queue and Available Tasks
• Users & Permissions
• Source