CLI Reference¶

Complete reference for all Consoul commands and options.

Table of Contents¶

consoul chat - Start an interactive chat session.
consoul describe - Describe Consoul CLI commands and their schemas.
consoul history - Manage conversation history.
consoul history clear - Delete all conversation history.
consoul history delete - Delete a conversation session.
consoul history export - Export conversation(s) to a file.
consoul history import - Import conversations from Consoul JSON export.
consoul history list - List recent conversation sessions.
consoul history search - Search conversation history using full-text search.
consoul history show - Show conversation details for a specific session.
consoul history stats - Show conversation history statistics.
consoul history summary - Show conversation summary for a specific session.
consoul init - Initialize a new Consoul configuration file.
consoul preset - Manage tool presets.
consoul preset list - List all available tool presets (built-in + custom).
consoul tui - Launch Consoul TUI.

Global Options¶

These options can be used with any command:

--help - Show help message and exit
--profile PROFILE - Configuration profile to use (default: default)
--list-profiles - List all available profiles and exit
--temperature FLOAT - Override model temperature (0.0-2.0)
--model TEXT - Override model name
--max-tokens INT - Override maximum tokens to generate

Commands¶

`consoul chat`¶

Start an interactive chat session with streaming responses.

Usage:

consoul chat [OPTIONS]

Description:

The chat command launches an interactive CLI session for conversing with AI models. Features include streaming token-by-token responses, rich markdown rendering, conversation history with context retention, history navigation (up/down arrows), and optional tool execution with approval.

Unlike the TUI mode, CLI chat provides a lightweight, single-session interface focused on quick interactions.

Options:

-m, --model TEXT - Model to use (e.g., gpt-4o, claude-3-5-sonnet-20241022, llama3)
--no-stream - Disable streaming responses (show complete response at once)
--no-markdown - Disable markdown rendering (show plain text)
--tools / --no-tools - Enable/disable tool execution (overrides config)
--multiline - Enable multi-line input mode (use Alt+Enter to submit)

Global Options:

--profile TEXT - Configuration profile to use
--temperature FLOAT - Override model temperature (0.0-2.0)
--max-tokens INT - Override maximum tokens to generate

Examples:

# Basic usage with default profile
consoul chat

# Use specific model
consoul chat --model gpt-4o

# Use specific profile
consoul --profile creative chat

# Disable tools and markdown
consoul chat --no-tools --no-markdown

# Multi-line mode for code blocks
consoul chat --multiline

In-Session Controls:

Enter - Send message
Ctrl+C or Ctrl+D - Quit session
Up/Down arrows - Navigate input history
Escape - Clear current input line

Slash Commands:

Type /help during the session to see available slash commands:

Command	Description
`/help`	Show available commands
`/clear`	Clear conversation history
`/tokens`	Show token usage and limits
`/stats`	Show detailed session statistics
`/exit`, `/quit`	Exit the chat session
`/model <name>`	Switch to different model mid-session
`/tools <on\\|off>`	Toggle tool execution
`/export <file>`	Export conversation to .md or .json

See CLI Chat Guide for comprehensive documentation.

`consoul describe`¶

Describe Consoul CLI commands and their schemas.

consoul describe [command_path] [options]

Arguments:

command_path - (optional, default: )
Type: text

Options:

-f, --format - Output format (default: json)
Type: choice
Choices: json, markdown
Default: json
-o, --output - Write output to file instead of stdout
Type: path
Default: ``
--indent - JSON indentation spaces (default: 2)
Type: integer
Default: 2
--compact - Compact JSON output (no indentation)
Type: boolean

`consoul history`¶

Manage conversation history.

consoul history

Subcommands:

clear - Delete all conversation history.
delete - Delete a conversation session.
export - Export conversation(s) to a file.
import - Import conversations from Consoul JSON export.
list - List recent conversation sessions.
search - Search conversation history using full-text search.
show - Show conversation details for a specific session.
stats - Show conversation history statistics.
summary - Show conversation summary for a specific session.

See individual command documentation for details.

`consoul history clear`¶

Delete all conversation history.

consoul history clear [options]

Options:

--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``
--yes - Confirm the action without prompting.
Type: boolean

`consoul history delete`¶

Delete a conversation session.

consoul history delete <session_id> [options]

Arguments:

session_id - (required)
Type: text

Options:

--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``
--yes - Confirm the action without prompting.
Type: boolean

`consoul history export`¶

Export conversation(s) to a file.

consoul history export [session_id] <output_file> [options]

Arguments:

session_id - (optional, default: )
Type: text
output_file - (required)
Type: path

Options:

-f, --format - Output format (default: json)
Type: choice
Choices: json, markdown, html, csv
Default: json
--all - Export all conversations (JSON format only)
Type: boolean
--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history import`¶

Import conversations from Consoul JSON export.

consoul history import <import_file> [options]

Arguments:

import_file - (required)
Type: path

Options:

--dry_run - Validate import file without importing
Type: boolean
--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history list`¶

List recent conversation sessions.

consoul history list [options]

Options:

-n, --limit - Number of conversations to show (default: 10)
Type: integer
Default: 10
--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history search`¶

Search conversation history using full-text search.

consoul history search <query> [options]

Arguments:

query - (required)
Type: text

Options:

-n, --limit - Maximum number of results to return (default: 20)
Type: integer
Default: 20
--model - Filter results by model name
Type: text
Default: ``
--after - Filter results after this date (ISO format: YYYY-MM-DD)
Type: text
Default: ``
--before - Filter results before this date (ISO format: YYYY-MM-DD)
Type: text
Default: ``
-c, --context - Number of surrounding messages to show (default: 2)
Type: integer
Default: 2
-f, --format - Output format (default: text)
Type: choice
Choices: text, json
Default: text
--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history show`¶

Show conversation details for a specific session.

consoul history show <session_id> [options]

Arguments:

session_id - (required)
Type: text

Options:

--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history stats`¶

Show conversation history statistics.

consoul history stats [options]

Options:

--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul history summary`¶

Show conversation summary for a specific session.

consoul history summary <session_id> [options]

Arguments:

session_id - (required)
Type: text

Options:

--db_path - Path to history database (default: ~/.consoul/history.db)
Type: path
Default: ``

`consoul init`¶

Initialize a new Consoul configuration file.

consoul init <config_path>

Arguments:

config_path - (required)
Type: path

`consoul preset`¶

Manage tool presets.

consoul preset

Subcommands:

list - List all available tool presets (built-in + custom).

See individual command documentation for details.

`consoul preset list`¶

List all available tool presets (built-in + custom).

consoul preset list

`consoul tui`¶

Launch Consoul TUI.

consoul tui [options]

Options:

--theme - Color theme (monokai, dracula, nord, gruvbox)
Type: text
Default: ``
--debug - Enable debug logging
Type: boolean
--log_file - Debug log file path
Type: path
Default: ``
--tools - Tool specification: 'all', 'none', 'safe', 'caution', 'dangerous', category names (search/file-edit/web/execute), or comma-separated tool names (bash,grep,code_search)
Type: text
Default: ``
--preset - Tool preset: 'readonly', 'development', 'safe-research', 'power-user', or custom preset name. Overrides --tools flag.
Type: text
Default: ``
--test_mode - Test mode (auto-exit)
Type: boolean

CLI Reference¶

Table of Contents¶

Global Options¶

Commands¶

consoul chat¶

consoul describe¶

consoul history¶

consoul history clear¶

consoul history delete¶

consoul history export¶

consoul history import¶

consoul history list¶

consoul history search¶

consoul history show¶

consoul history stats¶

consoul history summary¶

consoul init¶

consoul preset¶

consoul preset list¶

consoul tui¶

See Also¶

`consoul chat`¶

`consoul describe`¶

`consoul history`¶

`consoul history clear`¶

`consoul history delete`¶

`consoul history export`¶

`consoul history import`¶

`consoul history list`¶

`consoul history search`¶

`consoul history show`¶

`consoul history stats`¶

`consoul history summary`¶

`consoul init`¶

`consoul preset`¶

`consoul preset list`¶

`consoul tui`¶