285 lines
6.4 KiB
Groff
285 lines
6.4 KiB
Groff
.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
|