233 lines
6.2 KiB
Markdown
233 lines
6.2 KiB
Markdown
# HarborForge.Cli
|
|
|
|
`HarborForge.Cli` is the Go-based `hf` binary for HarborForge.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
go build -o ./bin/hf ./cmd/hf
|
|
```
|
|
|
|
Or use the bundled Makefile:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
To set the version at build time:
|
|
|
|
```bash
|
|
go build -ldflags "-X git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands.Version=1.0.0" -o ./bin/hf ./cmd/hf
|
|
```
|
|
|
|
The Makefile versioned equivalent is:
|
|
|
|
```bash
|
|
make build VERSION=1.0.0
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## Install
|
|
|
|
### Local install into a user bin directory
|
|
|
|
```bash
|
|
mkdir -p "$HOME/.local/bin"
|
|
go build -o "$HOME/.local/bin/hf" ./cmd/hf
|
|
chmod +x "$HOME/.local/bin/hf"
|
|
```
|
|
|
|
Make sure `~/.local/bin` is on `PATH` before invoking `hf` directly.
|
|
|
|
### OpenClaw profile install target
|
|
|
|
The OpenClaw plugin installer flow places the binary at:
|
|
|
|
```text
|
|
~/.openclaw/bin/hf
|
|
```
|
|
|
|
If you want the equivalent manual install:
|
|
|
|
```bash
|
|
mkdir -p "$HOME/.openclaw/bin"
|
|
go build -o "$HOME/.openclaw/bin/hf" ./cmd/hf
|
|
chmod +x "$HOME/.openclaw/bin/hf"
|
|
```
|
|
|
|
### Config location
|
|
|
|
`hf` resolves `.hf-config.json` relative to the binary directory, not the current working directory.
|
|
|
|
Examples:
|
|
- if the binary is `~/.local/bin/hf`, config lives at `~/.local/bin/.hf-config.json`
|
|
- if the binary is `~/.openclaw/bin/hf`, config lives at `~/.openclaw/bin/.hf-config.json`
|
|
|
|
This matters when testing multiple copies of the CLI side by side.
|
|
|
|
### Quick start after install
|
|
|
|
```bash
|
|
hf config --url http://127.0.0.1:8000
|
|
hf --help-brief
|
|
hf health
|
|
```
|
|
|
|
### Auth modes after install
|
|
|
|
- **Padded-cell mode** (`pass_mgr` available): run commands directly and let `hf` resolve secrets automatically.
|
|
- **Manual mode** (`pass_mgr` unavailable): pass `--token` to authenticated commands.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# padded-cell mode
|
|
hf task list
|
|
|
|
# manual mode
|
|
hf task list --token "$HF_TOKEN"
|
|
```
|
|
|
|
## Release Packaging
|
|
|
|
Cross-platform release builds are available through the Makefile:
|
|
|
|
```bash
|
|
make release VERSION=1.0.0
|
|
```
|
|
|
|
This produces versioned artifacts in `dist/` using a stable naming pattern:
|
|
|
|
```text
|
|
hf_<version>_<os>_<arch>
|
|
hf_<version>_<os>_<arch>.exe # Windows
|
|
```
|
|
|
|
Current release targets:
|
|
- `linux/amd64`
|
|
- `linux/arm64`
|
|
- `darwin/amd64`
|
|
- `darwin/arm64`
|
|
- `windows/amd64`
|
|
|
|
Examples:
|
|
- `dist/hf_1.0.0_linux_amd64`
|
|
- `dist/hf_1.0.0_darwin_arm64`
|
|
- `dist/hf_1.0.0_windows_amd64.exe`
|
|
|
|
## Package Layout
|
|
|
|
```text
|
|
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)
|
|
- Release automation beyond local `make release` packaging (checksums / archives / CI publishing)
|
|
- Integration tests
|