CLI Reference

OpenClacky provides two CLI commands: openclacky agent (the default) and openclacky server.

`openclacky agent`

Start an interactive agent session in the terminal. This is the default command — running clacky alone is equivalent to openclacky agent.

openclacky [agent] [options]

Options

Flag	Default	Description
`--mode`	`confirm_safes`	Permission mode (see below)
`--theme`	`hacker`	UI theme: `hacker` or `minimal`
`--path`	current dir	Project directory
`--agent`	`coding`	Agent profile: `coding`, `general`, or custom name
`-m, --message`	—	Run non-interactively with this message and exit
`-i, --image`	—	Image file path(s) to attach (use with `-m`)
`-c, --continue`	—	Continue the most recent session for this directory
`-l, --list`	—	List recent sessions
`-a, --attach`	—	Attach to session by number or session ID prefix
`--json`	false	Output NDJSON to stdout (for scripting/piping)
`-v, --verbose`	false	Show detailed output

Permission Modes

Mode	Behavior
`confirm_safes`	Auto-approve safe read operations; prompt for writes and shell commands (default)
`auto_approve`	Execute all tools automatically — no confirmation. Use with caution.
`confirm_all`	Auto-approve file/shell tools, but pause for interactive prompts

Agent Profiles

Profile	Description
`coding`	Full coding agent with all development tools (default)
`general`	General-purpose assistant with a lighter tool set
custom	Any profile defined in `~/.clacky/agents/<name>/`

Examples

# Start a new session in current directory
clacky

# Start in a specific directory with auto-approve
openclacky --path /path/to/project --mode auto_approve

# Non-interactive: send one message and exit
openclacky -m "Add a README to this project"

# Non-interactive with an image attachment
openclacky -m "What's in this screenshot?" -i /path/to/image.png

# Continue the most recent session
openclacky -c

# List recent sessions, then attach to the second one
openclacky -l
openclacky -a 2

# Attach by session ID prefix
openclacky -a b6682a87

# Pipe output as NDJSON for scripting
openclacky --json -m "Run the test suite"

`openclacky server`

Start the Web UI server. See Web Server for full details.

openclacky server [options]

Options

Flag	Default	Description
`--host`	`127.0.0.1`	Bind address
`--port`	`7070`	Listen port

Examples

# Start on default address
openclacky server

# Expose on all interfaces, custom port
openclacky server --host 0.0.0.0 --port 8080

Configuration

The CLI reads configuration from ~/.clacky/config.yml. API keys and model settings can also be provided via environment variables. See Agent Configuration for details.