Configuration

micasa has minimal configuration – it’s designed to work out of the box.

CLI#

micasa has three subcommands. run is the default and launches the TUI; config manages configuration (query values or open the config file in an editor); backup creates a database snapshot.

Usage: micasa <command> [flags]

Commands:
  run [<db-path>]         Launch the TUI (default).
  config get [<filter>]   Query config values with a jq filter.
  config edit             Open the config file in an editor.
  backup [<dest>]         Back up the database to a file.

Flags:
  -h, --help       Show context-sensitive help.
      --version    Show version and exit.

run (default)#

micasa [<db-path>] [flags]

demo#

micasa demo [<db-path>] [flags]

Launch with fictitious sample data. Without a path argument, uses an in-memory database.

To persist demo data for later:

micasa demo /tmp/my-demo.db   # creates and populates
micasa /tmp/my-demo.db        # reopens with the demo data

config get#

micasa config get [<filter>]

Query resolved configuration values using a jq filter expression. With no filter (or the identity .), the entire resolved configuration is printed as JSON.

micasa config get                      # full config (identity)
micasa config get .chat.llm.model      # current chat model name
micasa config get .extraction.llm      # extraction section
micasa config get '.chat.llm | keys'   # list keys in a section

API keys are stripped from the output to avoid accidentally leaking secrets (e.g. pasting output into a chat or issue).

config edit#

micasa config edit

Opens the config file in your preferred editor ($VISUAL, then $EDITOR, then a platform default). Creates the file with sensible defaults if it doesn’t exist yet.

backup#

micasa backup [<dest>] [--source <path>]

Creates a consistent snapshot using SQLite’s Online Backup API, safe to run while the TUI is open:

micasa backup ~/backups/micasa-$(date +%F).db
micasa backup --source /path/to/micasa.db ~/backups/snapshot.db

Platform data directory#

micasa uses platform-aware data directories (via adrg/xdg). When no path is specified (via argument or MICASA_DB_PATH), the database is stored at:

On Linux, XDG_DATA_HOME is respected per the XDG Base Directory Specification.

Database path resolution order#

The database path is resolved in this order:

1. Positional CLI argument, if provided
2. MICASA_DB_PATH environment variable, if set
3. Platform data directory (see table above)

The demo subcommand uses an in-memory database (:memory:) when no path argument is given.

Config file#

micasa reads a TOML config file from your platform’s config directory:

The config file is optional. If it doesn’t exist, all settings use their defaults. Unset fields fall back to defaults – you only need to specify the values you want to change.

Example config#

# micasa configuration
# Each section is self-contained. No section's values affect another section.

[chat]
# Set to false to hide the chat feature from the UI.
# enable = true

[chat.llm]
# LLM connection settings for the chat (NL-to-SQL) pipeline.
# provider = "ollama"
base_url = "http://localhost:11434"
model = "qwen3"
# api_key = ""
# timeout = "5m"
# effort = "medium"
# extra_context = "My house is a 1920s craftsman in Portland, OR."

[extraction]
# max_pages = 0

[extraction.llm]
# LLM connection settings for document extraction.
# enable = true
# provider = "ollama"
model = "qwen3"
# timeout = "5m"
# effort = "low"

[extraction.ocr]
# enable = true

[extraction.ocr.tsv]
# enable = true
# confidence_threshold = 70

[documents]
# max_file_size = "50 MiB"
# cache_ttl = "30d"

[locale]
# currency = "USD"

[chat] section#

Controls the chat (NL-to-SQL) feature and its LLM settings.

[chat.llm] section#

LLM connection settings for the chat pipeline. Each field has its own default; no values are inherited from other config sections.

[extraction.llm] section#

LLM connection settings for the document extraction pipeline. Fully independent from [chat.llm] – each pipeline has its own provider, model, and credentials.

[documents] section#

Document attachment limits and caching.

[extraction] section#

Document extraction pipeline settings.

[extraction.ocr] section#

OCR sub-pipeline settings. Requires tesseract and pdftocairo.

[extraction.ocr.tsv] section#

Spatial layout annotations (line-level bounding boxes) from tesseract OCR. Improves extraction accuracy for invoices and forms with tabular data, at ~2x token overhead.

[locale] section#

Locale and currency settings. Controls currency formatting across all money fields in the application.

Currency resolution order (highest to lowest):

1. Database value (authoritative once set – makes the DB file portable)
2. MICASA_LOCALE_CURRENCY environment variable
3. [locale] currency config value
4. Auto-detect from LC_MONETARY or LANG locale
5. USD fallback

Formatting is locale-correct: EUR uses comma decimals and period grouping (1.234,56), GBP uses the pound sign (£750.00), JPY uses yen with no decimal places, etc.

Supported LLM backends#

micasa talks to any server that implements the OpenAI chat completions API with streaming (SSE). All providers – including Ollama – communicate via OpenAI-compatible endpoints; there is no native SDK dependency on any provider.

Local backends#

Ollama is the primary tested backend:

Cloud providers#

micasa also supports cloud LLM providers. Set provider, base_url, and api_key in [chat.llm] and/or [extraction.llm]. Cloud providers use their own default base URLs when none is configured.

Override precedence#

Environment variables override config file values. The full precedence order (highest to lowest):

1. Environment variables
2. Config file values
3. Built-in defaults

Each config key has a corresponding env var shown in gray below the key name: MICASA_ + uppercase config path with dots replaced by underscores. MICASA_DB_PATH is an exception – it controls the database path and has no config file equivalent.

extra_context examples#

The extra_context field in [chat.llm] is injected into every system prompt sent to the chat LLM, giving it persistent knowledge about your situation:

[chat.llm]
extra_context = """
My house is a 1920s craftsman bungalow in Portland, OR.
Property tax is assessed annually in November.
The HVAC system is a heat pump (Mitsubishi hyper-heat) -- no gas furnace.
"""

This helps the model give more relevant answers without you repeating context in every question. Currency is configured separately via [locale] currency and is automatically available to the LLM – no need to mention it in extra_context.

Persistent preferences#

Some preferences are stored in the SQLite database and persist across restarts. These are controlled through the UI rather than config files: