CLI Reference

ghost daemon

Start the GHOST daemon (Discord bot + job scheduler).

ghost daemon

ghost init

Initialize workspace and config files.

ghost init

Creates ~/.config/ghost/config.toml and the workspace directory with default files.

ghost config

Read, write, and reload configuration values.

ghost config get <key>          # Get a config value (with defaults)
ghost config set <key> <value>  # Set a config value
ghost config reload             # Validate config and signal the daemon to reload

Examples:

Config examples

ghost config get discord.allowed_user_id
ghost config set timing.heartbeat_idle_minutes 10
ghost config set web.search_max_results 10
ghost config reload

ghost config reload

Validates config.toml and .env, then sends SIGHUP to a running daemon to apply changes without restarting.

ghost config reload

Hot-reloadable — the daemon picks up these changes immediately:

• model — default chat model
• timing — heartbeat, idle, and compaction intervals
• compaction — token thresholds and limits
• web — search provider, result counts
• docling — document import settings
• coding — coding session settings
• debug — log level and debug flags
• discord.allowed_user_ids — who can interact with GHOST
• embeddings.url and embeddings.model — embedding endpoint and model name

Requires restart — these settings are read once at startup:

• workspace — workspace directory path
• embeddings.dimension — vector size (changing this invalidates stored embeddings)
• discord.enabled — enables or disables the Discord interface

Embeddings model change

Changing embeddings.model without also changing embeddings.dimension may produce embeddings that are incompatible with existing ones in the database. Run ghost knowledge reindex after changing the model to regenerate all embeddings.

ghost auth

Manage authentication for providers.

ghost auth codex     # OpenAI OAuth flow (opens browser)
ghost auth status    # Check authentication status
ghost auth revoke    # Revoke OpenAI tokens

ghost job

Manage cron jobs.

ghost job list                   # List jobs with next-run times
ghost job validate <path>        # Validate job file syntax
ghost job run <name>             # Execute job immediately
ghost job logs [name]            # View job execution logs

ghost hack

Manage coding sessions. See GHOST HACK for details.

ghost hack start <dir> [--prompt "task"]   # Start a coding session
ghost hack resume <id> [--prompt "task"]   # Resume a previous session
ghost hack list                            # List recent sessions

ghost agent

Discover, validate, and inspect agents.

ghost agent list               # List all discovered agents
ghost agent validate [name]    # Validate agent Lua configs (all or one)
ghost agent status             # Running agents + recent runs
ghost agent show <run_id>      # Details of a specific run

ghost agent status

Table of running agents and recent completed/failed runs.

ghost agent status                     # Last 20 runs
ghost agent status --agent my-agent    # Filter by agent name
ghost agent status --limit 50          # Show more runs

Running agents appear first, sorted by start time.

ghost agent show

View the result of a specific agent run. Accepts a full run ID or a unique prefix (minimum 4 characters).

ghost agent show 01JQ8A2B              # Transcript only
ghost agent show 01JQ8A2B --full       # Include full message history
ghost agent show 01JQ8A2B --json       # JSON output
ghost agent show 01JQ8A2B --full --json

Failed runs automatically include the error message. Use --json for machine-readable output (e.g. piping to another agent).

ghost session

Inspect chat sessions.

ghost session list                              # Recent sessions (up to 50)
ghost session logs <session_id>                 # View messages
ghost session logs <session_id> --count 100     # More messages
ghost session logs <session_id> --around <id>   # Center on a message

ghost knowledge

Query and manage the knowledge base.

Search

ghost knowledge search <query>
ghost knowledge search <query> --kind note      # Filter by type
ghost knowledge search <query> --limit 20       # More results

Read

ghost knowledge get --title "Note Title"        # Get by title
ghost knowledge get <path>                      # Get by path

Graph

ghost knowledge graph <target>                  # Show connections
ghost knowledge graph <target> --direction out   # Outgoing only
ghost knowledge graph --orphans                  # Unconnected notes
ghost knowledge graph --stats                    # Edge/stub counts

Browse

ghost knowledge tags                             # Tags with counts
ghost knowledge recent                           # Recent activity
ghost knowledge recent --limit 50
ghost knowledge stats                            # Type counts
ghost knowledge references                       # All reference topics
ghost knowledge references --topic rust          # By topic

Maintenance

ghost knowledge reindex                          # Sync files → database
ghost knowledge reindex --skip-embeddings        # Skip embedding gen

ghost reference

Import, update, and delete external reference material. See Reference Import for details.

Import

# From a git repository (preferred for doc sets)
ghost reference import git --url <url> --topic <name> \
    [--paths dir1,dir2] [--extensions .md,.rs] [--ref <tag-or-branch>]

# By crawling a website (fallback)
ghost reference import crawl --url <url> --topic <name> \
    [--max-depth 3] [--max-pages 50]

Update

ghost reference update --topic <name>              # Re-fetch from source
ghost reference update --topic <name> --ref v2.0   # Switch branch/tag

Re-fetches from the original source and applies changes. New files are added, changed files are updated, and files deleted upstream are removed — unless cited by notes, in which case they are moved to _orphaned/.

Delete

ghost reference delete --topic <name>

Removes the topic, all its references, embeddings, import metadata, and workspace files.

ghost db

Repair the SQLite database by rebuilding file-backed state from the workspace and copying operational tables into a fresh candidate DB.

Repair

ghost db repair
ghost db repair --dry-run

ghost db repair --dry-run is the safest default. It builds a candidate database beside ghost.db, verifies that DB-only tables were preserved, writes a JSON repair report, and leaves the live DB untouched.

Run it when GHOST or ghost knowledge search starts failing with SQLite corruption errors such as database disk image is malformed.

Repair artifacts are written next to the live database:

• ghost.db.repair-<timestamp>.candidate
• ghost.db.repair-<timestamp>.report.json
• ghost.db.backup-<timestamp> on a successful non-dry-run swap

Fail-closed behavior

Repair does not mutate the corrupted DB in place. If it cannot safely preserve DB-only tables or cannot reconstruct file-backed state from the workspace, it leaves ghost.db untouched and exits with an error.

ghost document

Import documents (PDF, DOCX, etc.) via docling-serve. See Reference Import for details.

ghost document import file --path <path> --topic <name>

For URLs, download the file first (curl -L -o uploads/doc.pdf <url>), then import with the command above.

Optional flags (use only when explicitly needed):

Flag	Default	Purpose
--no-ocr	OCR on	Skip OCR for digital PDFs
--page-range "1-10"	full doc	Import specific pages only
--timeout 900	600s	Extend timeout for large docs

ghost web

Web search and fetch.

ghost web search <query>                         # Search with Brave
ghost web search <query> -n 10                   # More results
ghost web fetch <url>                            # Extract content
ghost web fetch <url> --readability              # Article mode
ghost web fetch <url> --raw                      # Raw HTML

ghost start

Start all registered services (top-to-bottom), then start the GHOST daemon via the OS service manager.

ghost start

Stops on first service failure — the daemon is not started if any service fails to come up. Shows ghost status output at the end.

ghost stop

Stop the GHOST daemon, then stop all registered services (bottom-to-top, best-effort).

ghost stop

Always attempts all service stops even if some fail. Shows ghost status output at the end.

ghost services

Manage the service registry (services.toml). Generated during ghost init, editable via these commands.

ghost services list                                      # Show registered services
ghost services add --name <n> [--start ".."] [--stop ".."] [--update ".."] [--status ".."]
ghost services remove <name>                             # Unregister a service
ghost services update                                    # Run update commands (stops on first failure)
ghost services status                                    # Check process-level status

ghost status

Show config validity, daemon status, and service health at a glance.

ghost status

Checks:

• Config — loads and validates config.toml, reports parse errors
• Daemon — checks whether ghost-daemon is active via systemd/launchd
• Services — probes each configured service URL (embeddings, search, Crawl4AI, Docling, browsers)

Complementary to ghost services status — this checks HTTP health, while ghost services status checks process-level status.

ghost version

Print the GHOST version.

ghost version