This commit is contained in:
zphinx
@@ -53,9 +53,22 @@ This document describes tai's current runtime architecture, module responsibilit
|
||||
|
||||
## Data Stores
|
||||
|
||||
- Runbook store (Tier 2): local ChromaDB path, default `~/.tai/runbooks`
|
||||
- Runbook store (Tier 2): local ChromaDB path or remote ChromaDB HTTP endpoint (`--runbooks`, `runbooks --store`)
|
||||
- Run history store (Tier 3): SQLite file/URL or PostgreSQL DSN (`--history-db`)
|
||||
- Session logs: optional JSONL file configured by `--log-file`
|
||||
|
||||
External DB auth can be provided by CLI options or dotenv file (`--env-file`) and is resolved without executing downloaded runbook content.
|
||||
|
||||
## Runbook Source Ingestion
|
||||
|
||||
`tai runbooks sync --path` and `tai runbooks add` support runbook/playbook source retrieval from:
|
||||
|
||||
- local filesystem paths
|
||||
- SSH URIs (`ssh://...`) via read-only remote fetch (`find`, `cat`)
|
||||
- HTTP/HTTPS URLs (single `.md` file or webroot index with `.md` links)
|
||||
|
||||
Remote source content is materialized into temporary local files, embedded, and then indexed into the target ChromaDB store.
|
||||
|
||||
## Retrieval Layers
|
||||
|
||||
- Tier 1 (implemented): in-memory semantic retrieval over diagnostic chunks
|
||||
|
||||
284
docs/tai.1
Normal file
284
docs/tai.1
Normal file
@@ -0,0 +1,284 @@
|
||||
.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
|
||||
Reference in New Issue
Block a user