HarborForge/plans/harborforge-cli-go-plan.md

HarborForge CLI (Go Binary) Plan

Goal

Build a Go-based HarborForge CLI binary.

This CLI is intended to work in two modes:

1. With padded-cell / pass_mgr available
   • agents can use it directly
   • secrets and generated credentials can be managed automatically
2. Without padded-cell installed
   • humans can still use it by explicitly passing tokens/passwords

Important: do not directly migrate the old Python CLI from HarborForge.Backend/cli.py as-is. The old CLI is only a reference for existing command coverage. The new CLI should be implemented as a standalone Go binary.

---

High-Level Direction

• Language: Go
• Delivery: single binary
• Config file: .hf-config.json
• Config location: same directory as the CLI binary
• Secret manager integration: pass_mgr
• Design goal:
  • compatible with automated agent usage
  • also usable manually without padded-cell/pass_mgr

---

Binary / Config Model

Assume CLI name is placeholder <cli-name> for now.

Config file location

The command:

<cli-name> config --url <hf-url>

must write:

{
  "base-url": "<hf-url>"
}

into:

<binary-dir>/.hf-config.json

That means config resolution is based on the directory where the binary lives, not cwd and not home directory.

Config contents (initial)

{
  "base-url": "http://127.0.0.1:8000"
}

Initial config scope is intentionally small.

---

CLI Command Requirements

1. Config command

Set HarborForge base URL

<cli-name> config --url <hf-url>

Behavior:

• write/update base-url in <binary-dir>/.hf-config.json

Set account-manager token through pass_mgr

<cli-name> config --acc-mgr-token <token>

Behavior:

• execute:

pass_mgr set --public --key hf-acc-mgr-token --secret $token

If this fails, terminate with:

--acc-mgr-token can only be set with padded-cell plugin

This is intentionally a hard error because this path depends on pass_mgr availability.

---

2. Normal authenticated commands

General form:

<cli-name> <command> <arg> [--token <token>]

Token resolution order

1. If --token <token> is explicitly provided, use it.
2. Otherwise try:

pass_mgr get-secret --key hf-token

If this fails, print stderr and terminate with exactly:

--token <token> required or execute this with pcexec

Notes

• Normal API commands should support optional --token
• They should also support agent-oriented execution when pass_mgr exists
• They should remain usable manually when users explicitly provide --token

---

3. Special command: create-account

Command shape:

<cli-name> create-account --user <username> [--pass <password>] [--acc-mgr-token <account-mgr-token>]

Special rules

• create-account cannot accept --token
• create-account should not attempt normal token auto-resolution
• It uses account-manager token instead of the normal user token flow

Password resolution

If --pass <password> is not explicitly provided, try:

pass_mgr generate --key hf --username $username

If this fails, print stderr and terminate with exactly:

--pass <password> required or execute with pcexec

Account-manager token resolution

If --acc-mgr-token <token> is not explicitly provided, try:

pass_mgr get-secret --public --key hf-acc-mgr-token

If this fails, print stderr and terminate with exactly:

--acc-mgr-token <token> required or execute with pcexec

Purpose

This command is meant to work very naturally with padded-cell-driven agent flows while still allowing manual operator input.

---

pass_mgr Integration Rules

The CLI should treat pass_mgr as an optional capability.

With padded-cell / pass_mgr

Expected conveniences:

• persistent token lookup from hf-token
• public account-manager token lookup from hf-acc-mgr-token
• password generation via pass_mgr generate

Without padded-cell / pass_mgr

Expected fallback:

• users manually pass --token
• users manually pass --pass
• users manually pass --acc-mgr-token

Error philosophy

Do not silently ignore secret-manager failures. If the command depends on pass_mgr fallback and it is unavailable, fail with the exact operator-facing messages defined above.

---

Backend / Permission Requirements

The new CLI plan implies backend support for an account-manager capability.

New protected default role

In addition to existing undeletable default roles:

• admin
• guest

add:

• account-manager

account-manager semantics

• role is part of initial bootstrap/default roles
• role cannot be deleted
• role permissions should be limited to:
  • create account

This is intentionally narrow. It should not inherit general admin privileges.

Backend work implied by this plan

• seed account-manager during initial role setup
• protect it from deletion the same way default protected roles are protected
• add a backend permission / route policy for account creation by account-manager
• make sure CLI create-account maps onto this backend capability cleanly

---

Proposed CLI Implementation Phases

Phase 1 — Foundation

• create Go module
• add binary entrypoint
• add config loader/saver for <binary-dir>/.hf-config.json
• add HTTP client wrapper
• add token resolution helpers
• add pass_mgr execution wrapper
• define clear error handling / stderr behavior

Phase 2 — Auth + Config Flows

• implement config --url
• implement config --acc-mgr-token
• implement shared --token resolution behavior
• implement request auth injection

Phase 3 — Account Creation Flow

• implement create-account
• support --user
• support optional --pass
• support optional --acc-mgr-token
• add pass_mgr-backed fallback logic
• enforce exact required error messages

Phase 4 — Command Expansion

Use existing HarborForge.Backend/cli.py only as feature inventory reference. Do not copy its architecture directly.

Potential later commands:

• projects
• users
• milestones
• tasks
• proposes
• monitor-related commands
• health / version

Phase 5 — Hardening

• tests for config path resolution
• tests for pass_mgr failure behavior
• tests for explicit token/password override behavior
• tests for exact stderr messages
• packaging / release pipeline for binary builds

---

Open Questions

1. Final binary name:

   • harborforge
   • hf
   • harborforge-cli
   • or another name

2. create-account backend API contract:

   • new dedicated route?
   • or reuse/extend current user creation route?

3. Whether normal token lookup should support additional fallbacks later:

   • env var
   • config file token
   • OS keychain

Current plan intentionally keeps fallback logic narrow and explicit.

---

Non-Goals (for now)

• do not directly port old Python CLI architecture
• do not require padded-cell for all usage
• do not store auth token in .hf-config.json
• do not make account-manager an admin-like role
• do not broaden account-manager permissions beyond account creation in the initial design