How mrazeekk/alex-cli works
Alex is a Debian-focused terminal assistant. Users request help or error analysis through the CLI; Alex asks OpenAI for structured guidance, displays proposed commands, and—when requested and approved—executes them with risk checks. Separate CLI paths cover service diagnosis, key/configuration management, and system health checks. The shell hook supplies failed-command context for error analysis. The graph reflects documented capabilities and shown imports/calls; unsampled behavior is represented only where the README documents it.
Main entry points: cli.py Command interface · openai_client.py Structured AI client · service_diag.py Service diagnosis · doctor.py System doctor
Components 20
CLI workflows
- Command interface
alex/cli.py - Failed-command log
- Shell error hook
scripts/alex-shell-hook.sh - Error log filtering
alex/errors.py
Diagnostics
- Service diagnosis
alex/service_diag.py - Service name resolver
alex/service_resolve.py - System doctor
alex/doctor.py - Systemd and journal
AI and presentation
- Structured AI client
alex/openai_client.py - OpenAI API
- Response schema
alex/schema.py - System information
alex/system.py - Response renderer
alex/render.py
Credentials and settings
- API key management
alex/auth.py - Stored API key
- Key availability check
alex/utils.py - User preferences
alex/user_config.py - Default settings
alex/config.py
System execution
- Command executor
alex/executor.py
Other components
- Terminal user
Connections 28
- Terminal user → Command interface: invokes
README.md - Shell error hook → Failed-command log: records failures
README.md - Command interface → Error log filtering: reads and filters
alex/cli.py - Command interface → Failed-command log: reads error context
README.md - Command interface → Key availability check: checks key
alex/cli.py - Command interface → Structured AI client: requests analysis
alex/cli.py - Command interface → Command executor: runs approved commands
alex/cli.py - Command interface → Response renderer: renders guidance
alex/cli.py - Command interface → Service diagnosis: starts diagnosis
alex/cli.py - Command interface → Service name resolver: resolves service name
alex/cli.py - Command interface → System doctor: runs checks
alex/cli.py - Command interface → API key management: manages credentials
alex/cli.py - Command interface → User preferences: edits preferences
alex/cli.py - Service diagnosis → Command executor: runs probes
alex/service_diag.py - Service diagnosis → Systemd and journal: queries unit and logs
alex/service_diag.py - Service diagnosis → Structured AI client: requests next probes
alex/service_diag.py - Service diagnosis → Response renderer: renders findings
alex/service_diag.py - Service name resolver → Command executor: lists service units
alex/service_resolve.py - System doctor → API key management: checks key status
alex/doctor.py - System doctor → User preferences: checks config path
alex/doctor.py - System doctor → Response renderer: prints results
alex/doctor.py - Structured AI client → OpenAI API: sends structured request
alex/openai_client.py - Structured AI client → Response schema: gets response schema
alex/openai_client.py - Structured AI client → System information: gets system context
alex/openai_client.py - Structured AI client → User preferences: loads preferences
alex/openai_client.py - Structured AI client → Default settings: uses model default
alex/openai_client.py - API key management → Stored API key: reads and writes
alex/auth.py - Key availability check → API key management: loads key into environment
alex/utils.py