Gemini CLI Commands¶
This document describes the custom commands available in the Gemini CLI for the Homelab project.
/homelab status¶
Provide a "bird's eye view" of the lab, checking Proxmox node health, listing active Docker containers, and reporting on active Conductor tracks.
Usage¶
Implementation¶
The command performs the following checks:
1. Proxmox Status: Uses pve04__get_cluster_status and pve04__list_nodes to report node health and resource usage.
2. Docker Status: Maps subdirectories in docker/ containing compose.yaml and lists running containers using docker ps.
3. Conductor Status: Parses conductor/tracks.md to identify active tracks and their progress.
References¶
/deploy <app_name> <type>¶
Automate the creation of a new application directory in docker/ or lxc/ based on existing templates.
Usage¶
Implementation¶
The command uses scripts/deploy.py to:
1. Scaffold Directory: Creates docker/<app_name> or lxc/<app_name>.
2. Copy Templates: Uses docker/.template or lxc/.template.
3. Substitution: Replaces Jinja2 variables (e.g., {{ APP_NAME }}) in .j2 files.
4. Register Track: Automatically creates a new Conductor track for the deployment.
/doc new <name> <category>¶
Automate the creation of new documentation files using existing templates.
Usage¶
Implementation¶
The command uses scripts/doc_new.py to:
1. Template Selection: Selects appropriate template based on category (apps, tools, etc.).
2. Variable Substitution: Prompts for and replaces variables like APP_PORT, CONFIG_PATH, etc.
3. File Creation: Creates the new Markdown file in the correct directory.
4. Navigation Update: Triggers task generate-docs-nav to update the site navigation.
/pve sync¶
Trigger synchronization tasks and verify that DNS rewrites and configurations are consistent across multiple Proxmox nodes.
Usage¶
Implementation¶
The command uses scripts/pve_sync.py to:
1. AdGuard Sync: Restarts adguardhome-sync.service.
2. Traefik Check: Scans pve/traefik/conf.d/ for consistency.
3. DNS Check: Encourages manual rewrite verification via manage_dns.
/pve log <node> [service]¶
Fetch and summarize recent logs from a specific Proxmox node or service.
Usage¶
Implementation¶
The command uses scripts/pve_log.py to:
1. Fetch Logs: Retrieves cluster logs via Proxmox API.
2. Filter: Filters by node and optional service keyword.
3. Summarize: Formats entries with level-based coloring and timestamps.
/task summary¶
Automatically summarize work done in the current task and update the project plan.
Usage¶
Implementation¶
The command uses scripts/task_summary.py to:
1. Identify Task: Finds the task marked as [~] in the active track's plan.md.
2. Draft Note: Generates a Git Note draft with modified files and a summary placeholder.
3. Update Status: Changes the task status to [x] in plan.md.
4. Checkpoint Check: Alerts if a phase or track is complete and requires a checkpoint.
/check secrets¶
Verify the encryption status of all sensitive files project-wide to prevent accidental leaks.
Usage¶
Implementation¶
The command uses scripts/check_secrets.py to:
1. Scan: Identifies .env, *.enc, and files with secret or creds in their name.
2. Verify: Decrypts .enc files and compares them with unencrypted versions if they exist.
3. Audit: Reports unencrypted sensitive files that are not ignored by Git.
4. Report: Provides a summarized status of all sensitive files.
/homelab update <app_name>¶
Pull updates and restart services for Docker and LXC applications.
Usage¶
Implementation¶
The command uses scripts/homelab_update.py to:
1. Identify App: Locates the application in docker/, lxc/, or pve/.
2. Execute Update:
- For Docker: Runs docker compose pull and docker compose up -d.
- For LXC: Executes the application's update.sh script.
3. Report: Provides a status summary of the update process.
/homelab backup <target>¶
Trigger manual backups for specific applications or configurations.
Usage¶
Implementation¶
The command uses scripts/homelab_backup.py to:
1. Resolve Target: Maps aliases (e.g., agh, patchmon) or direct names to directories.
2. Execute Backup: Runs the task backup command in the target directory.
3. Verify: Checks for the update of .enc files to confirm the backup was successful and encrypted.
/rotate secret <app_name> <key>¶
Securely generate and rotate credentials in encrypted environment files.
Usage¶
Implementation¶
The command uses scripts/rotate_secret.py to:
1. Decrypt: Temporarily decrypts the .env.enc file for the specified application using SOPS.
2. Generate: Generates a new high-entropy secret string.
3. Update: Replaces the existing value for the specified key in the decrypted .env file.
4. Encrypt: Re-encrypts the file and securely deletes the temporary unencrypted file.
:search: /audit deps [path]¶
Scan Docker image dependencies across compose.yaml files and report outdated versions.
Usage¶
Implementation¶
The command uses scripts/audit_deps.py to:
1. Scan: Recursively searches the specified path (defaults to docker/) for compose.yaml files.
2. Extract: Parses image tags from identified files.
3. Query: Fetches the latest available tags from Docker Hub or GHCR.
4. Compare: Identifies outdated versions using semantic version comparison (handling 'v' prefixes and common suffixes).
5. Report: Displays a formatted table with current vs. latest versions and update status.
/dashboard add <name> <group>¶
Automate the addition of new services to the homepage dashboard.
Usage¶
Implementation¶
The command uses scripts/dashboard_add.py to:
1. Validate Group: Ensures the target group exists in services.yaml.
2. Metadata Prompt: Prompts for icon, URL, and description.
3. YAML Update: Appends the service to the correct group while preserving comments and formatting using ruamel.yaml.
Planned Commands¶
The following commands are currently in the implementation queue:
/verify backups: Automate the integrity and decryption verification of backups./map network: Generate a visual Mermaid map of the homelab network and traffic flow.