.TH TAI 1 "2026-05-11" "tai 0.4.0" "User Commands"
.SH NAME
tai \- read-only Linux troubleshooting assistant with SSH diagnostics and AI analysis
.SH SYNOPSIS
.B tai
.RI [ GLOBAL_OPTIONS ]
.B run
.I ISSUE
.RI [ RUN_OPTIONS ]
.PP
.B tai
.B history
.RI [ HISTORY_OPTIONS ]
.PP
.B tai
.B runbooks
.B sync
.RI [ SYNC_OPTIONS ]
.PP
.B tai
.B runbooks
.B list
.RI [ LIST_OPTIONS ]
.PP
.B tai
.B runbooks
.B add
.I FILE
.RI [ ADD_OPTIONS ]
.SH DESCRIPTION
.B tai
connects to Linux hosts over SSH, collects read-only diagnostics, and can ask an OpenAI-compatible model for grounded analysis.
.PP
Remote runbook (playbook) sources can be local paths, SSH URIs, or HTTP/HTTPS webroots.
Downloaded runbook content is never executed. It is stored as text and parsed for retrieval context only.
.SH COMMANDS
.SS run
Main troubleshooting entrypoint.
.TP
.BI --host " HOST"
Target host to troubleshoot.
.TP
.BI --port " PORT"
SSH port (default: 22).
.TP
.BI --path " PATH"
Target path to inspect. Repeatable.
.TP
.BI --identity-file " FILE"
SSH private key path.
.TP
.BI --jump-host " HOST"
SSH bastion/jump host.
.TP
.B --ignore-ssh-config
Ignore ~/.ssh/config and rely only on CLI options.
.TP
.B --probe / --no-probe
Enable or disable connectivity probe.
.TP
.B --collect / --no-collect
Collect baseline diagnostics.
.TP
.B --analyze / --no-analyze
Send diagnostics to AI for analysis.
.TP
.B --interactive / --no-interactive
Interactive follow-up mode.
.TP
.BI --ai-host " URL"
OpenAI-compatible AI backend URL.
.TP
.BI --model " NAME"
Model name for analysis.
.TP
.BI --ai-key " KEY"
API key for AI backend.
.TP
.BI --ai-timeout-seconds " SECONDS"
Timeout for AI requests.
.TP
.BI --ai-max-tokens " TOKENS"
Max completion tokens.
.TP
.BI --embed-model " NAME"
Embedding model for RAG.
.TP
.B --no-rag
Disable RAG retrieval.
.TP
.B --rag-debug / --no-rag-debug
Print retrieval debug output.
.TP
.BI --runbooks " STORE"
Runbook store path or remote Chroma URL.
.TP
.BI --runbooks-user " USER"
Runbook store login/user for remote Chroma URLs.
.TP
.BI --runbooks-password " PASSWORD"
Runbook store password for remote Chroma URLs.
.TP
.BI --history-db " TARGET"
History DB target: SQLite path/URL or PostgreSQL DSN.
.TP
.BI --history-db-user " USER"
History DB login/user for external database URLs.
.TP
.BI --history-db-password " PASSWORD"
History DB password for external database URLs.
.TP
.B --history / --no-history
Enable or disable history DB reads/writes.
.TP
.BI --output-file " FILE"
Write analysis to file.
.TP
.BI --output-format " FORMAT"
Output format: markdown or json.
.TP
.BI --log-file " FILE"
Optional JSONL event log path.
.TP
.BI --env-file " FILE"
Optional dotenv file used to resolve DB credentials.
.SS history
Search/list indexed troubleshooting history.
.TP
.BI --query " TEXT"
Optional keyword search in issue/summary.
.TP
.BI --host " HOST"
Filter by host.
.TP
.BI --limit " N"
Maximum sessions to show.
.TP
.BI --export " FILE"
Export results as Markdown.
.TP
.BI --history-db " TARGET"
History DB target: SQLite path/URL or PostgreSQL DSN.
.TP
.BI --history-db-user " USER"
History DB login/user for external database URLs.
.TP
.BI --history-db-password " PASSWORD"
History DB password for external database URLs.
.TP
.BI --env-file " FILE"
Optional dotenv file used to resolve DB credentials.
.SS runbooks sync
Index all runbooks from source path.
.TP
.BI --path " SOURCE"
Runbook source: local directory, ssh://host/path, or http(s) webroot URL.
.TP
.BI --store " TARGET"
ChromaDB store path or remote URL.
.TP
.BI --store-user " USER"
Runbook store login/user for remote Chroma URLs.
.TP
.BI --store-password " PASSWORD"
Runbook store password for remote Chroma URLs.
.TP
.BI --ai-host " URL"
OpenAI-compatible AI backend URL.
.TP
.BI --embed-model " NAME"
Embedding model name.
.TP
.BI --ai-key " KEY"
API key for AI backend.
.TP
.BI --identity-file " FILE"
SSH private key for ssh:// source.
.TP
.BI --jump-host " HOST"
SSH bastion for ssh:// source.
.TP
.B --ignore-ssh-config
Ignore ~/.ssh/config for ssh:// source.
.TP
.BI --env-file " FILE"
Optional dotenv file used to resolve DB credentials.
.SS runbooks list
List indexed runbooks.
.TP
.BI --store " TARGET"
ChromaDB store path or remote URL.
.TP
.BI --store-user " USER"
Runbook store login/user for remote Chroma URLs.
.TP
.BI --store-password " PASSWORD"
Runbook store password for remote Chroma URLs.
.TP
.BI --env-file " FILE"
Optional dotenv file used to resolve DB credentials.
.SS runbooks add
Index one runbook file.
.TP
.BI FILE
Runbook source: local file, ssh://host/path/file.md, or HTTP/HTTPS URL ending in .md.
.TP
.BI --store " TARGET"
ChromaDB store path or remote URL.
.TP
.BI --store-user " USER"
Runbook store login/user for remote Chroma URLs.
.TP
.BI --store-password " PASSWORD"
Runbook store password for remote Chroma URLs.
.TP
.BI --ai-host " URL"
OpenAI-compatible AI backend URL.
.TP
.BI --embed-model " NAME"
Embedding model name.
.TP
.BI --ai-key " KEY"
API key for AI backend.
.TP
.BI --identity-file " FILE"
SSH private key for ssh:// source.
.TP
.BI --jump-host " HOST"
SSH bastion for ssh:// source.
.TP
.B --ignore-ssh-config
Ignore ~/.ssh/config for ssh:// source.
.TP
.BI --env-file " FILE"
Optional dotenv file used to resolve DB credentials.
.SH ENVIRONMENT
The following variables are recognized for DB credentials:
.TP
.B TAI_HISTORY_DB_USER
History DB user when --history-db points to external database.
.TP
.B TAI_HISTORY_DB_PASSWORD
History DB password when --history-db points to external database.
.TP
.B TAI_RUNBOOK_STORE_USER
Runbook store user for remote ChromaDB.
.TP
.B TAI_RUNBOOK_STORE_PASSWORD
Runbook store password for remote ChromaDB.
.SH SECURITY NOTES
.TP
\(bu
SSH diagnostics are validated against read-only command policy.
.TP
\(bu
Web/SSH runbook content is never executed.
.TP
\(bu
Webroot ingestion accepts only Markdown-like payloads and skips HTML/non-markdown wrappers.
.SH FILES
.TP
.I ~/.tai/history.db
Default local history database.
.TP
.I ~/.tai/runbooks
Default local runbook store path.
.SH EXAMPLES
.PP
Analyze with PostgreSQL history DB credentials loaded from .env:
.PP
.nf
$ tai run "sshd auth failed" --host bastion01 --collect --analyze \
    --history-db postgresql://db.internal:5432/tai --env-file ./.env
.fi
.PP
Sync runbooks from HTTPS webroot to remote ChromaDB:
.PP
.nf
$ tai runbooks sync --path https://kb.example/runbooks/ \
    --store https://chroma.internal:8443 --env-file ./.env
.fi
.SH SEE ALSO
.BR README.md ,
.BR docs/ARCHITECTURE.md