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`	Register the project, scaffold `.fp/`, and prompt to add agent-specific instructions
`fp init --agent claude`	Same as `fp init`, and write `FP_CLAUDE.md` / ensure `CLAUDE.md` `@`-includes it
`fp init --agent standard`	Same as `fp init`, and write `FP_AGENTS.md` / ensure `AGENTS.md` `@`-includes it
`fp init --agent codex`	Alias for `--agent standard`
`fp init --agent skip`	Same as `fp init`; explicit choice to add no extra agent files
`fp agent setup claude`	Add/refresh `FP_CLAUDE.md` and the `CLAUDE.md` include in an already-initialized project
`fp agent setup standard`	Add/refresh `FP_AGENTS.md` and the `AGENTS.md` include in an already-initialized project
`fp agent setup codex`	Alias for `fp agent setup standard`

Project Sync and Remote Access

Command	Description
`fp project link`	Link the local project to a remote project and write `.fp/remote.toml`
`fp project sync [issue-id]`	Synchronize local issues with the linked remote project
`fp project clone [project-id]`	Clone a remote fp project locally
`fp project remote`	Show the effective remote project identity and its sources
`fp project remote stamp`	Write `.fp/remote.toml` for an already-linked project
`fp project unlink`	Remove the local link; remote data is not deleted

Use these commands to link local fp data to a remote project. For CI and cloud agents, follow Cloud Agents to use the REST API without a local fp store. Local fp usage does not require FP_REMOTE or FP_TOKEN.

Workflow Primers

Command	Description
`fp guide plan`	Print the planning skill primer
`fp guide implement`	Print the implementation skill primer
`fp guide brainstorm`	Print the brainstorm-authoring primer (alias: `bs`)
`fp guide extension`	Print the extension-authoring primer (aliases: `extensions`, `ext`)
`fp guide <skill> --references <name>`	Print companion reference material (e.g. `fp guide brainstorm --references mermaid`)

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

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
`fp comment update COMMENT_ID "text"`	Edit an existing comment (alias `edit`)
`fp comment delete COMMENT_ID`	Soft-delete a comment

Brainstorms

See Brainstorms for the full guide.

Command	Description
`fp bs create <file.md> [--title "..."] [--format json]`	Create a brainstorm from a markdown file
`fp bs list [--deleted] [--format json]`	List brainstorms
`fp bs show ID [--with-comments] [--resolved] [--version N] [--desktop]`	Dump brainstorm markdown to stdout
`fp bs open ID`	Open a brainstorm in the Mac desktop app
`fp bs update ID <file.md> [--title "..."]`	Update with new markdown (creates a new version)
`fp bs delete ID`	Soft-delete a brainstorm
`fp bs versions ID [--format json]`	List version history
`fp bs comments ID [--format json]`	List comments on a brainstorm
`fp bs comments add ID "text"`	Add a comment (prints a `::comment-ref{}` snippet)
`fp bs comments resolve ID COMMENT_ID`	Resolve a comment thread
`fp bs comments delete ID COMMENT_ID`	Soft-delete a comment

fp brainstorm and fp bs are interchangeable; fp bs comments also accepts the alias fp bs comment. Short ID prefixes are accepted anywhere an ID is required.

Issue Statuses

Issues have three statuses:

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

Priority Levels

Issues support priority levels: low, medium, high, critical.

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

Getting Help

Every command supports --help:

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