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¶

/homelab status

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¶

• Conductor Workflow
• Proxmox API

/deploy <app_name> <type>¶

Automate the creation of a new application directory in docker/ or lxc/ based on existing templates.

Usage¶

/deploy my-new-app docker

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¶

/doc new my-app apps

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¶

/pve sync

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¶

/pve log pve04 pveupdate

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¶

/task summary

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¶

/check secrets

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¶

/homelab update my-app

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¶

/homelab backup agh

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¶

/rotate secret activepieces DB_PASSWORD

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¶

/audit deps docker/filebrowser

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¶

/dashboard add my-app IoT

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.

/app remove <name>¶

Automate the removal of a service from the homelab, including Traefik, DNS, and Homepage.

Usage¶

/app remove my-old-app

Implementation¶

The command performs the following cleanup: 1. Traefik: Deletes the service's configuration file in pve/traefik/conf.d/. 2. Dashboard: Uses scripts/dashboard_remove.py to remove the service from services.yaml and re-balance category columns. 3. DNS: Removes corresponding DNS rewrites in AdGuard Home. 4. Sync: Commits changes and triggers /traefik update and /homepage update.

/homepage update¶

Update the homepage dashboard by syncing configuration changes and restarting the service.

Usage¶

/homepage update

Implementation¶

1. Identify Configuration: Locates the local configuration in pve/homepage/config/.
2. Sync Configuration: The homepage LXC (vmid 110) on pve04 has the configs symlinked to the repository. Ensure local changes are committed and pushed.
3. Restart Service: Executes task restart within the pve/homepage directory or via SSH to restart the homepage.service in the LXC on pve04.

/traefik update¶

Update the traefik edge router by syncing configuration changes and restarting the service.

Usage¶

/traefik update

Implementation¶

1. Identify Configuration: Locates the local configuration in pve/traefik/.
2. Sync Configuration: The traefik LXC (vmid 111) on pve04 has the repository in /root/git/nicholaswilde/homelab/. Ensure local changes are committed and pushed.
3. Restart Service: Executes systemctl restart traefik via SSH in the LXC on pve04.

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.