Skip to content

Add GitHub Copilot/Claude instruction #583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
agners merged 2 commits into from
Aug 12, 2025
Merged

Add GitHub Copilot/Claude instruction #583

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8fa0752
Add GitHub Copilot/Claude instruction
agners Aug 12, 2025
9e23947
Apply suggestions from code review
agners Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Home Assistant CLI

## Project Overview
This is the official Home Assistant CLI tool written in Go, providing command-line
interface to interact with the Home Assistant Supervisor. The CLI enables users to
manage add-ons, control the core system, handle audio/network settings, manage
backups, and perform various system operations.

The CLI is communicating with the Supervisor using the Supervisor's HTTP REST API.

## Repository Structure
- **`main.go`** - Entry point of the application
- **`cmd/`** - Contains all CLI command implementations using Cobra framework
- **`client/`** - HTTP client functionality for API communication
- **`spinner/`** - Progress spinner implementation
- **Root files** - Configuration and documentation

## Key Technologies
- **Language**: Go (use modern syntax)
- **CLI Framework**: Cobra (github.com/spf13/cobra)
- **HTTP Client**: Resty (github.com/go-resty/resty/v2)
- **Configuration**: Viper (github.com/spf13/viper)
- **Logging**: Logrus (github.com/sirupsen/logrus)

## Available Commands
The CLI provides the following main command categories:
- `addons` - Install, update, remove and configure Home Assistant add-ons
- `audio` - Audio plug-in management
- `authentication` - Authentication for Home Assistant users
- `cli` - CLI plug-in management
- `core` - Home Assistant Core control
- `dns` - DNS plug-in management
- `docker` - Docker related configuration
- `hardware` - System hardware information
- `host` - Host OS control
- `info` - General Home Assistant information
- `multicast` - Multicast plug-in configuration
- `network` - Network configuration and management
- `observer` - Observer plug-in management
- `os` - Home Assistant OS specific operations
- `resolution` - Resolution center for issues and solutions
- `backups` - Backup creation, restoration, and management
- `supervisor` - Supervisor monitoring and control
Comment on lines +26 to +43
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Optionally validate listed command categories against cobra definitions

To keep this list in sync, you can auto-check for top-level cobra “Use” strings.

🏁 Script executed:

#!/bin/bash
set -euo pipefail

declare -a cmds=(addons audio authentication cli core dns docker hardware host info multicast network observer os resolution backups supervisor)

missing=0
for c in "${cmds[@]}"; do
  if rg -n $'Use:\\s*"'$c'"' -S >/dev/null; then
    echo "✓ $c"
  else
    echo "✗ $c (not found in code)"
    missing=1
  fi
done

exit $missing

Length of output: 1664

Ensure hardware command exists or update docs

The .github/copilot-instructions.md lists a hardware command, but no corresponding cobra definition (Use: "hardware") was found:

• Affected location:

  • .github/copilot-instructions.md (lines 26–43): the - hardware – System hardware information entry

Next steps:

  • Either implement a cobra command with Use: "hardware" (e.g. in cmd/hardware.go)
  • Or remove/update this line in the documentation to keep the list in sync

You can confirm with:

rg -n 'Use:\s*"hardware"' -S
🤖 Prompt for AI Agents 
.github/copilot-instructions.md around lines 26 to 43: the docs list a
"hardware" CLI command but there is no corresponding cobra command
implementation; either add a cobra command with Use: "hardware" (e.g., create
cmd/hardware.go registering the command in root/cmd init) that implements the
described functionality or remove/update the "hardware" entry from the markdown
so docs and code stay in sync; run the suggested ripgrep check (rg -n
'Use:\s*"hardware"' -S) to verify presence after you add the command and ensure
the command is wired into the CLI root.


## Development Environment
- **API Endpoint**: Configurable via `SUPERVISOR_ENDPOINT` environment variable
- **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable
- **Config File**: Optional config file support (default: `$HOME/.homeassistant.yaml`)

Comment on lines +45 to +49
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Add a brief security note for API tokens and verify default config path

  • Suggest warning to keep SUPERVISOR_API_TOKEN out of logs and shell history.
  • Verify the default config file path is correct.

Suggested doc tweak:

 - **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable
 - **Config File**: Optional config file support (default: `$HOME/.homeassistant.yaml`)
+  - Security: Avoid exposing `SUPERVISOR_API_TOKEN` in shell history or logs; prefer `.env` files or a secrets manager.

Verify config defaults:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n 'viper\.(SetConfig(Name|File)|AddConfigPath|SetDefault)' -A 2 -S || true
rg -n '\.homeassistant' -S || true

Length of output: 1273

Add security note for API token; default config path confirmed

Verified that the default config file path ($HOME/.homeassistant.yaml) is accurate (see README.md:20 and cmd/root.go:80,142–146). Please update .github/copilot-instructions.md (lines 45–49) with the following tweak:

- **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable
+ **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable  
  - Avoid exposing the token in shell history or logs; consider using `.env` files or a secrets manager.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Development Environment
- **API Endpoint**: Configurable via `SUPERVISOR_ENDPOINT` environment variable
- **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable
- **Config File**: Optional config file support (default: `$HOME/.homeassistant.yaml`)
## Development Environment
- **API Endpoint**: Configurable via `SUPERVISOR_ENDPOINT` environment variable
- **Authentication**: Uses API tokens via `SUPERVISOR_API_TOKEN` environment variable
- Avoid exposing the token in shell history or logs; consider using `.env` files or a secrets manager.
- **Config File**: Optional config file support (default: `$HOME/.homeassistant.yaml`)
🤖 Prompt for AI Agents 
In .github/copilot-instructions.md around lines 45 to 49, update the
"Development Environment" block to add a short security note about the API token
and confirm the default config path: keep the existing entries for
SUPERVISOR_ENDPOINT, SUPERVISOR_API_TOKEN and the Config File path
($HOME/.homeassistant.yaml), and append one sentence advising that
SUPERVISOR_API_TOKEN should be treated as sensitive (set via environment
variables or secrets manager, do not commit to repo or store in plaintext) so
contributors know to protect the token.

## Build Commands
- **Build**: `CGO_ENABLED=0 go build -ldflags="-s -w" -o "ha"`
- **Test**: `go test ./...`
- **Format**: `gofmt -s`

Comment on lines +50 to +54
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Formatting command should write changes; consider standard ‘go fmt’

“gofmt -s” only prints to stdout. Use -w, or just “go fmt ./...” for module-aware formatting.

-- **Format**: `gofmt -s`
+- **Format**: `gofmt -s -w .`  (or `go fmt ./...`)

Optionally verify if a Makefile or linting targets exist:

🏁 Script executed:

#!/bin/bash
set -euo pipefail
fd -a '^Makefile$' || true
rg -n 'golangci-lint|gofumpt|go fmt|gofmt' -S || true

Length of output: 163

Apply formatting changes with -w or use go fmt

The current command gofmt -s only prints diffs; it doesn’t modify files. Update it to write changes in-place.

• File: .github/copilot-instructions.md (around line 52)

- **Format**: `gofmt -s`
+ **Format**: `gofmt -s -w .`  (or `go fmt ./...`)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Build Commands
- **Build**: `CGO_ENABLED=0 go build -ldflags="-s -w" -o "ha"`
- **Test**: `go test ./...`
- **Format**: `gofmt -s`
## Build Commands
- **Build**: `CGO_ENABLED=0 go build -ldflags="-s -w" -o "ha"`
- **Test**: `go test ./...`
- **Format**: `gofmt -s -w .` (or `go fmt ./...`)
🤖 Prompt for AI Agents 
In .github/copilot-instructions.md around lines 50 to 54, the Build Commands
section uses `gofmt -s` which only prints diffs and does not modify files;
change it to run formatting in-place by replacing that entry with either `gofmt
-s -w` or `go fmt ./...` so the command writes updates to files rather than just
displaying them.

## File Organization Patterns
- Command files follow naming pattern: `<component>_<action>.go`
- Each command typically has its own file in the `cmd/` directory
- Helper functions are in `client/helper.go`
- Main client logic is in `client/client.go`

## Architecture Notes
- Uses Cobra for command structure and flag parsing
- Resty for HTTP API calls to Home Assistant Supervisor
- Viper for configuration management
- Logrus for structured logging
- Custom spinner implementation for progress indication

## Testing
- Unit tests available in `client/helper_test.go`
- Test command: `go test ./...`

## Contributing Guidelines
1. Create feature branch
2. Commit changes
3. Rebase against master
4. Run tests with `go test ./...`
5. Format code with `gofmt -s`
6. Create Pull Request

This CLI is designed to work with Home Assistant Supervisor API and is commonly used in
Home Assistant Operating System environments, SSH add-ons, and development setups.
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.github/copilot-instructions.md
Loading