HarborForge.Cli

HarborForge.Cli is the Go-based hf binary for HarborForge.

Build

go build -o ./bin/hf ./cmd/hf

To set the version at build time:

go build -ldflags "-X git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands.Version=1.0.0" -o ./bin/hf ./cmd/hf

Run

# Show help
./bin/hf --help

# Show only permitted commands
./bin/hf --help-brief

# Show version
./bin/hf version

# Check API health
./bin/hf health

# Configure API URL
./bin/hf config --url http://your-harborforge:8000

# View current config
./bin/hf config

# JSON output
./bin/hf version --json

Package Layout

cmd/hf/          CLI entrypoint
internal/
  client/        HTTP client wrapper for HarborForge API
  commands/      Command implementations
  config/        Config file resolution and management (.hf-config.json)
  help/          Help and help-brief renderer with detailed leaf help
  mode/          Runtime mode detection (padded-cell vs manual)
  output/        Output formatting (human-readable, JSON, tables)
  passmgr/       pass_mgr integration for secret resolution

Runtime Modes

• Padded-cell mode: When pass_mgr is available, auth tokens are resolved automatically. Manual --token flags are rejected.
• Manual mode: When pass_mgr is not available, --token must be provided explicitly to authenticated commands.

Current Status

Implemented

Foundation:

• Go module and binary entrypoint
• Config file resolution relative to binary directory
• Runtime mode detection (pass_mgr present/absent)
• HTTP client wrapper (GET/POST/PUT/PATCH/DELETE)
• Output formatting (human-readable + --json)
• Auth token resolution (padded-cell + manual)

Help system:

• Top-level and group/leaf help rendering (--help / --help-brief)
• Permission-aware command visibility via /auth/me/permissions
• Detailed leaf help text for all commands, with padded-cell/manual auth flag differences
• Nested help coverage for config, monitor server, and monitor api-key subtrees
• (not permitted) rendering for unauthorized commands

Core commands:

• hf version, hf health, hf config (show / --url / --acc-mgr-token)

Resource commands (all implemented with list/get/create/update/delete + special actions):

• hf user — create, list, get, update, activate, deactivate, delete
• hf role — list, get, create, update, delete, set-permissions, add-permissions, remove-permissions
• hf permission — list
• hf project — list, get, create, update, delete, members, add-member, remove-member
• hf milestone — list, get, create, update, delete, progress
• hf task — list, get, create, update, transition, take, delete, search
• hf meeting — list, get, create, update, attend, delete
• hf support — list, get, create, update, take, transition, delete
• hf propose — list, get, create, update, accept, reject, reopen
• hf comment — add, list
• hf worklog — add, list
• hf monitor — overview, server (list/get/create/delete), api-key (generate/revoke)

Pending

• Backend code-based endpoint support (some commands still use id-based API routes)
• Cross-platform binary packaging / release pipeline
• Integration tests