CLI Overview

[view as markdown]

The fp CLI is the primary interface for agent-native issue tracking. All commands work locally and are designed to be used by both humans and AI agents.

Commands

Project Setup

Command	Description
`fp init`	Initialize `.fp/` in your project
`fp setup claude`	Configure Claude Code integration

Issue Management

Command	Description
`fp issue create --title "..."`	Create a new issue
`fp issue create --title "..." --parent ID`	Create a sub-issue
`fp issue create --title "..." --property labels=frontend,backend`	Create with extension fields
`fp issue list`	List all issues
`fp issue list --status todo`	Filter by status
`fp issue show ID`	Show issue details and comments
`fp issue update --status STATUS ID`	Update issue status
`fp issue update --property labels=frontend ID`	Update extension fields
`fp issue assign ID --rev COMMIT`	Attach commit(s) to an issue
`fp issue diff ID`	Show diff for issue’s commit range
`fp issue files ID`	Show files changed in commit range

Command	Description
`fp tree`	View the full issue hierarchy
`fp context ID`	Load full issue context (for agents)
`fp comment ID "message"`	Add a comment to an issue

Brainstorms

Command	Description
`fp bs create <file>`	Create a brainstorm from an HTML file
`fp bs list`	List all brainstorms
`fp bs show ID`	Show brainstorm HTML (or open in desktop with `--desktop`)
`fp bs open ID`	Open brainstorm in desktop app
`fp bs update ID --file <path>`	Publish a new version
`fp bs delete ID`	Delete a brainstorm
`fp bs comments ID`	List comments on a brainstorm
`fp bs comments add ID "text"`	Add a comment (use `--selector` to pin to an element)
`fp bs comments delete ID COMMENT_ID`	Delete a comment
`fp bs versions ID`	List version history

Agent Identity

Command	Description
`fp agent whoami`	Show current agent identity

Issue Statuses

Issues have three statuses:

Status	Meaning
`todo`	Planned, not yet started
`in-progress`	Actively being worked on
`done`	Completed

VCS refs are captured on status transitions:

Base commit — captured when moving to in-progress
Tip commit — captured when moving to done

This enables fp issue diff and fp issue files to show exactly what changed.

Priority Levels

Issues support priority levels: low, medium, high.

fp issue create --title "Fix critical bug" --priority high

Getting Help

Every command supports --help:

fp --help
fp issue --help
fp issue create --help