lokictl Reference

Quick Start

lokictl ships next to the server binary in every release package (see Installation). On the machine running the server it finds the server without configuration; for a remote server, see the end of this section.

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
   --wait blocks until the job finishes and prints the final job object; the exit code is 0 for completed and 3 otherwise. To watch the job's log while it runs, use --follow. The same flags re-run or resume an existing job:
   lokictl job run describe --apply missing "D:/photos/2024" --follow
lokictl job copy <id> --follow
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.

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

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.

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:

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.

Code is coloured by role: literal --flag <placeholder> /path ENV_VAR "value" [optional]

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, group delete, workflow delete, deps delete, index delete, index prune. -y is accepted as a synonym.

category delete additionally refuses, with exit 2, to remove a category that still owns tag assignments unless --allow-nonempty is also present.

media cleanup and media thumbnail-cleanup delete data without --yes. Use --dry-run first. pool destroy deletes cloud resources without --yes.

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 copy, and job resume (--field is job run only):

Job object fields: id, command, arguments, input, original_input, state (pending, in_progress, paused, completed, cancelled, error; the last three are terminal), 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.

group

Tag groups are a visual level between a category and its tags, for example a Series category with one group per show holding per-season tags. Grouping changes only how the taxonomy panel lays tags out; it never changes what a tag query matches. Every command except group remove requires --category, because group labels are unique per category.

--stdin reads one tag label per line. To turn grouping off for a whole category without deleting groups, use category grouping <label> off.

pool

GPU worker pools place the local AI engines (retouch, reshoot, segment, and the other loki-* engines) on remote workers: loki-worker nodes reached over HTTP, and RunPod serverless endpoints. Commands that change placement read the engines configuration with GET /api/engines, edit it, and write it back with PUT /api/engines, printing the server's response. Adding a pool while the strategy is local switches the strategy to pool. The same settings are on the server's Config page, GPU Engines tab.

Flags for pool create:

Transfer flags (pool add-runpod, pool create runpod-serverless) give a serverless pool an S3 bucket to pass files through. Without one, files up to 7 MB travel inline in the request: stills work, video references do not.

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

Move files on disk and in the library

The move task moves files and re-points every library reference in one step: tags, embeddings, faces, scan markers, battle log, duplicate groups, the in-memory vector and face indexes, and .vtt transcript sidecars. Moves across drives or filesystems copy, flush, and then remove the source. Items already at the destination count as in place, so re-running a partial move is safe. If any item fails, the job ends in error with a list of what was not moved.

The input is files, a folder, or a query. A single folder's media files move into --target with their sub-folders kept; files that are not media stay where they are, and folders the move empties are removed. Several folders keep their own names under the target. Loose files lose their common parent folder.

Files already moved by another tool

Run a saved workflow

Group tags inside a category

Delete a category safely

Run engines on RunPod

Install a model

CI or automation with a scoped key

Environment Variables

Notes and Limits

• The server streams job stdout over SSE and does not persist it, except for the cleanup tasks, whose final job object carries the log. --follow on job run and job copy sees every line because it subscribes before the job exists; job logs and job resume --follow see lines from the moment they attach.
• 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