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.

Output / Error Contract

Human-readable mode

Default output is human-readable:

list commands render simple tables
get/detail commands render key-value output
empty lists render (no results)

JSON mode

--json can be supplied globally and produces structured JSON on stdout.

Current contract:

success payloads go to stdout as JSON
errors go to stderr as plain text
the CLI does not wrap successful payloads in a universal envelope yet
list/get payloads preserve canonical code-bearing fields whenever the backend already returns them

This is intentionally simple so agents can pipe hf ... --json into other tooling without first stripping banners or mixed text.

Exit / stderr conventions

Current CLI convention is:

exit 0 on success
exit 1 on command/validation/runtime errors
user-facing errors are written to stderr
success output is written to stdout

There is not yet a finer-grained exit-code taxonomy; callers should currently treat any non-zero exit as failure.

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

4.2 KiB Raw Blame History