Skip to content

lokust CLI reference

Thin client over the lokustd daemon. All state lives in the daemon; the CLI is a command interface.

Configuration env vars: - LOKUST_URL — daemon URL (default http://127.0.0.1:7700)

Exit codes: 0 on success, 1 on any error (including daemon unreachable).

lokust init

Initialize the current directory as a LOKUST project. Creates a new default session (5 agents) and writes its ID to .lokust/session. Subsequent lokust session run commands in this directory resolve the session automatically.

lokust init

Output: 

Created session a3f8b2c1
Linked to project: /path/to/project
a3f8b2c1-...full-uuid

lokust session new

Create a new session with the default 5-agent workflow. Does not auto-link to a project directory.

lokust session new

Output: session UUID to stdout; creation confirmation to stderr.

lokust session workflow <file.json>

Create a session from a custom workflow definition. See workflow format.

lokust session workflow workflows/ipad-streaming-portal.json

Agents are defined in the JSON with custom system prompts and task prompts. The session is linked to the current directory if not already initialized.

lokust session ls

List all sessions managed by the daemon.

lokust session ls

Output: 

ID         STATUS     PHASES         TOKENS         BY
a3f8b2c1   running    2/5             7609          user
b7cd9041   completed  5/5            49793          user

lokust session run [id]

Run all remaining phases of a session until completion or failure. Streams status updates as each phase completes.

lokust session run              # uses .lokust/session
lokust session run a3f8b2c1     # explicit id

Per-phase output: 

✓ Phase 1/5 — Architect Agent  37192ms · 2064 tokens · 6905 bytes

lokust session status [id]

Show session lifecycle state and per-phase metrics.

lokust session status

Output: 

Session a3f8b2c1
Status:  paused
Tokens:  7609
Duration: 163014ms

  ✓ 1  Architect Agent          30052ms · 1754 tokens
  ✓ 2  Security Agent           65621ms · 5855 tokens
  ○ 3  Integration Agent        0ms · 0 tokens
  ○ 4  Testing Agent            0ms · 0 tokens
  ○ 5  Documentation Agent      0ms · 0 tokens

Status icons: ○ queued, ● running, ◉ paused, ✓ completed, ✗ failed.

lokust session pause [id]

Freeze the session and export a .lok file. No new phases start; any in-flight work stops at the next checkpoint.

lokust session pause

Output: 

Paused session a3f8b2c1
Exported session-a3f8b2c1.lok (29.0 KB)
Transfer to another device and run:
  lokust session import session-a3f8b2c1.lok

lokust session export [id] [file]

Export a session to a .lok file without pausing. Use lokust session pause when you want to stop execution.

lokust session export a3f8b2c1 my-session.lok

lokust session import <file.lok>

Import a session from a .lok file. The session is stored in ~/.lokust/sessions/ and becomes available to all other commands.

lokust session import session-a3f8b2c1.lok

Output: 

Imported session a3f8b2c1
Resume with: lokust session run a3f8b2c1

Shorthand forms

When invoked outside a session subcommand, positional args are forwarded:

lokust run              # == lokust session run
lokust status           # == lokust session status
lokust pause            # == lokust session pause
lokust export out.lok   # == lokust session export

Session ID resolution

Commands that take an optional id: 1. If an id is passed explicitly, it wins. 2. Otherwise, if .lokust/session exists in the current directory, that is used. 3. Otherwise, the command errors.

IDs can be passed in full UUID form or as the first 8 characters.