CLM(1) - General Commands Manual
clm - LLM agent with a Lua plugin system
clm
setup
clm
[-H | --headless]
[-S | --no-stream]
[-V | --version]
[-a name | --agent name]
[-f prompt | --forever prompt]
[-m provider/model-id | --model provider/model-id]
[--provider name]
[-o prompt | --oneshot prompt]
[-p dir | --plugins dir]
[-r [id | --resume [id]]]
[-u base | --url base]
clm runs a conversational LLM agent against any OpenAI-compatible chat completions endpoint (llama.cpp, Ollama, OpenAI, Anthropic's OpenAI-compatible endpoint), with a Lua plugin system for custom tools; see clm-tool(5). With no options, and when both standard input and standard output are a terminal, clm runs its interactive curses(3) UI. Otherwise it falls back to a plain line-oriented REPL on standard input/output, which is also what --oneshot uses.
clm setup
writes a starter
config.lua
and
secrets.lua
into
XDG_CONFIG_HOME/clm
(or
~/.config/clm
if
XDG_CONFIG_HOME
is unset) and seeds the builtin plugins into its
plugins
subdirectory; see
clm-config(5).
Safe to re-run: it never overwrites a file that already exists.
The options are as follows:
-a name, --agent name
Use the agent profile named name (~/.config/clm/agents/name.lua) . If omitted, the agent key in config.lua is used, or otherwise the top-level model setting applies directly with no named profile.
-f prompt, --forever prompt
Interactive UI mode only. Submit prompt immediately, then automatically resubmit it every time a turn completes with nothing else queued, so the agent keeps going without a human re-prompting it each turn.
-H, --headless
Force the plain stdio REPL even when standard input and standard output are both a terminal.
-m provider/model-id, --model provider/model-id
A "provider/model-id" spec, same form and meaning as config.lua's top-level model (clm-config(5)): provider names an entry in providers to connect through, and model-id is the literal wire model id requested (also the key into that provider's models subtable, if it has a matching override entry there). A bare model-id with no "/" is instead used directly as a literal model id to request from --url (or whatever connection is otherwise active), with no provider lookup and no per-model overrides applied. Overrides whatever the active agent profile or config.lua's top-level model would otherwise supply.
--provider name
Name of an entry in config.lua's providers table (clm-config(5)), overriding which provider connection (endpoint, key, wire dialect) backs the selected model, independent of -m. Useful for failing over to a backup endpoint for the current model.
-o prompt, --oneshot prompt
Run a single prompt headlessly and exit, printing only the assistant's reply (plus any tool-call/error lines) to standard output. The process exits 0 if the turn completed successfully, or 1 otherwise.
-p dir, --plugins dir
Load Lua plugins from
dir
instead of the default
XDG_CONFIG_HOME/clm/plugins.
-r [id, --resume [id]]
Resume the saved session
id
in the interactive UI, replaying its transcript and continuing the
conversation in the same session log.
With no
id,
present a numbered list of saved sessions to pick from.
Sessions are logged automatically to
XDG_STATE_HOME/clm
(default
~/.local/state/clm)
,
one append-only
.jsonl
file per session; on exit the session id is printed for later
resumption, and a session in which nothing was said is deleted.
The
/clear
command starts a fresh session file, leaving the old one resumable.
Incompatible with
--oneshot
and
--headless.
-S, --no-stream
Request non-streamed responses instead of the default server-sent-events streaming.
-u base, --url base
Base API endpoint. /chat/completions is appended automatically; do not include it in base. Defaults to http://127.0.0.1:8081/v1.
-V, --version
Print the version number and exit.
-h, --help
Print usage and exit.
CLM_API_KEY
Bearer token sent as
Authorization: Bearer key
on every request to the configured endpoint.
Takes precedence over any
api_key
set in
config.lua
or an agent profile.
Servers that need no authentication (most local llama.cpp/Ollama
setups) can leave this unset.
XDG_CONFIG_HOME
Base directory for clm/config.lua, clm/secrets.lua, clm/plugins/, and clm/agents/. Defaults to ~/.config if unset.
CLM_DEBUG_LOG
Path to a file that internal debug logging is appended to. Unset (the default) disables logging entirely, nothing is written, and the check is cheap enough to leave alone in production.
~/.config/clm/config.lua
Provider, model, agent, and per-tool plugin configuration; see clm-config(5).
~/.config/clm/secrets.lua
API keys and other secrets, kept separate from
config.lua
so the latter can be shared or checked into dotfiles.
Mode 0600;
clm
warns (via
CLM_DEBUG_LOG)
if it is readable by group or other.
~/.config/clm/agents/*.lua
Per-agent profiles, each overriding or extending config.lua's settings; see clm-config(5).
~/.config/clm/plugins/*.lua
Lua plugins, each registering one or more tools; see clm-tool(5).
The clm utility exits 0 on success, and >0 if an error occurs. Under --oneshot, the exit status instead reflects whether that single turn completed successfully (0) or not (1).
clm_agent(3), clm-config(5), clm-tool(5)
clm - July 6, 2026