CLI Reference

The CLI (zlogic) is a Rust terminal front-end that runs the real engine in the same process. It has four run modes, decided by the first argument:

Mode	Invocation	Notes
Interactive TUI	no arguments (default)	full-screen; raw mode / alt-screen
One-shot	--prompt <text>	runs one turn, then exits — pipe friendly, add --print json
Markdown render	--render-md [path]	renders markdown to ANSI on stdout, no TUI
daemon	first argument daemon	hands off to the daemon CLI (start a local/remote daemon or manage paired devices)

The daemon is not a clap sub-command: with the first argument daemon, the rest is parsed by crates/daemon's CLI (the same implementation behind zlogic daemon …). See Remote daemon & pairing.

Common flags

Flag	Values	Default	Description
--prompt <text>	any text	—	enter one-shot mode: run a single turn and exit, no TUI
--model <id>	model id	—	model preference for this turn / session
--theme <id>	auto, dark, light, blood, cyberpunk, god, matrix, mono, monokai	auto	theme; auto probes the terminal background
--locale <tag>	auto, zh-CN, en-US	auto	UI language
--print <shape>	text, json	text	one-shot output shape; json prints event JSON-lines
--plan	—	off	Plan mode (read-only planning)
--cwd <path>	directory	process cwd	working directory for the turn / workspace
--session <id>	session id	new	resume the session with this id
--resume [<id>]	session id	new	resume the most recent session (no value), or a specific id (mutually exclusive with --session)
--quiet	—	off	one-shot: suppress thinking / tool output on stderr
--permission <mode>	auto, deny, approve-all	auto	non-interactive approval posture
--god	—	off	full-authorization mode (danger theme; maps to approve-all)
--render-md [path]	path or -	- (stdin)	render markdown to ANSI, then exit
--width <cols>	columns	terminal width, else 80	render width for --render-md
--probe	—	—	diagnostics: probe terminal capabilities and print them, then exit
-h / --help	—	—	clap help (includes the daemon hand-off note)

Examples:

# interactive TUI
zlogic

# one-shot: one turn to stdout
zlogic --prompt "hello"

# one-shot as JSON event stream
zlogic --prompt hi --print json

# render markdown from stdin to ANSI
printf '**hi** `x`' | zlogic --render-md -

# resume the most recent session
zlogic --resume

Starting a workspace

An interactive TUI launch (no --prompt / --resume / --session, stdin and stdout both a terminal) does not auto-register a workspace:

1. If the current directory (or its git root / an already-registered ancestor) is inside a workspace, it is used directly;
2. otherwise a prompt offers create a workspace here / choose from the list (Esc cancels).

Every other path (one-shot, --resume, --session, non-interactive terminal) keeps the old behavior: open_at auto-registers by its anchoring rules — scripts cannot answer an interactive question, so they never get stuck on one. During a TUI session, /workspace opens the workspace panel at any time.

Terminal capability diagnostics: --probe

--probe prints capability probing results and exits (pure diagnostics — no session, no TUI, no state change):

$ zlogic --probe
terminal_kind=Windows
color_tier=Rich
icon_tier=Unicode
ambiguous_wide=false
background=Dark
supports_sync=true
legacy_windows_console=false
probe_background=Some(Dark)
probe_ambiguous_wide=Some(false)
probe_supports_sync=Some(true)

The first three lines are environment heuristics; the probe_* lines are actual measurements (OSC 11 background, CSI 6n wide chars, DECRQM 2026) and win. Typical use: on Windows, if cmd launched from Windows Terminal shows ASCII icons, run this once — a process started via Win+R or the Start menu never sees WT_SESSION, and the CSI 6n measurement promotes narrow-rendered terminals back to Unicode. A bare conhost (legacy console) reports legacy_windows_console=true or ambiguous_wide=true.

In-TUI slash commands

The TUI is keyboard-driven; / opens the command palette. Built-in commands (they switch modes or open overlays; skills appear here too once installed — see Plugins & Skills):

Command	Effect
/help	show all commands (built-ins + installed skills)
/model [query]	list / switch models and providers (type to filter)
/theme	switch theme
/session	session history / switch session
/workspace	workspace panel (left column workspaces, right column session list)
/new	start a fresh session
/compact	summarise older context now
/stats	usage statistics
/info	current session info
/plan [on|off|toggle]	toggle Plan mode
/approval [auto|deny|all]	switch approval mode
/lang [zh-CN|en-US]	switch UI language
/view [minimal|normal|verbose]	live-view detail level

Skills are invoked the same way: install a skill and its directory name becomes a /name command (see Plugins & Skills).

Approving actions from the terminal

Sensitive actions (write files, run commands, access external resources) request authorization in the terminal before running. Reply with the scope of the grant:

• once — allow this one time only
• session — don't ask again in this session
• always / project — persist for this working directory

Confirmations and forms (e.g. a skill asking for input) are answered the same way. For non-interactive one-shot runs use --permission deny (fail closed) or --permission approve-all when you know what you are doing.

Model & key management

Provider and model configuration is YAML (models.yaml), but keys are never written there:

# store a provider key in the OS keyring
zlogic key add openai

# list which providers have keyring entries (masked)
zlogic key list

# verify a credential against the provider
zlogic key verify openai gpt-4o

# remove a keyring entry
zlogic key remove openai --yes

Keys also resolve from environment variables by default (auto_detect_env: true in models.yaml): export DEEPSEEK_API_KEY=sk-… and the DeepSeek provider shows up. See Key Management.

Exit codes

• 0 — success (one-shot completed; daemon subcommands succeeded; TUI exited normally)
• 1 — failure (bad arguments, engine startup failure, daemon service error)

Ctrl-C cancels the current turn in the TUI (does not kill the process); in one-shot mode a broken pipe is treated as success (exit 0).