Documentation
Hostplan CLI reference
Hostplan CLI reference for storing, reading, sharing, approving, stacking, revising, searching, and completing coding-agent plans.
Install
Hostplan requires Bun and Node 20 or newer. Install the public package globally with Bun, then run hsp from any project.
bun add --global hostplan
hsp --helpnpm install --global hostplan also works when Bun is already installed. Source installs remain available from the GitHub repository.
Store a plan
hsp add PLAN.md
hsp add -c "# Title\n..." -t "Title"
hsp add PLAN.md --public
hsp add PLAN.md --local
hsp add PLAN.md --status approved
hsp add PLAN.md --jsonHostplan detects the current Git project and branch. Use --project or--branch only when the detected scope is not the intended one.
Read and find plans
Get
hsp get <id> prints the body. hsp get latest finds the newest plan in the current project and branch.List
hsp list uses the current scope. Add -a for all plans or-p <project> for one project.Search
hsp search rate limiting runs full-text search across plan titles and bodies.Next
hsp next returns the first plan that is neither complete nor blocked by an unfinished dependency.Manage lifecycle and tasks
hsp status <id>
hsp status <id> approved
hsp status <id> in-progress
hsp tasks <id>
hsp check <id> 2 3
hsp check <id> 2 --undo
hsp status <id> doneNew plans start as drafts. An implementing agent should not begin until the plan is approved; move it to in progress when work starts and to done only after the required outcome and checks are complete.
Build ordered plan stacks
hsp stack 01-schema.md 02-api.md 03-ui.md
hsp add 04-rollout.md --after <id>
hsp stack <id>
hsp nextEach plan in a stack depends on the one before it. Completing a step unblocks the next without merging several implementation phases into one oversized prompt.
Revise and share
hsp update <id> PLAN.md
hsp share <id>
hsp publish <id>
hsp unpublish <id>
hsp rotate <id>Updating revises the same plan id and URL. Publishing is deliberate; private plans get a share code, and rotating it invalidates the previous coded link.
Connect a hosted deployment
hsp login
hsp whoami
hsp logoutOnce signed in, hsp add writes locally and pushes the same plan id to the deployment. A failed remote push does not discard the local plan.
Automation contract
Every command that returns data accepts --json. Prefer structured output in agents and CI. Set HOSTPLAN_REMOTE and HOSTPLAN_TOKEN for unattended hosted access, and never print the token into a plan or build log.