Fiftth CLI

. . . ....

The official CLI for Fiftth.

Fiftth CLI is the entrypoint for the full Fiftth execution flow: authenticate, select a workspace, register local repositories, validate planning context, recover task-linked branches, and launch Nexus orchestration for agent execution.

How The Flow Works

. . . .... 1. Shell setup

You install the CLI, authenticate with Fiftth, select a workspace, choose a default model, and register the local repositories that belong to your tasks.

This can be done from any directory. The CLI persists its own configuration and repository mappings, so ftt checkout does not require you to be inside a git repository.

. . . .... 2. Planning flow

Inside a repository, ftt planning-context validates whether the current repo is actually linked to the selected task before you create or refine a PRD.

The typical planning sequence is:

1. write-prd to pressure-test the design and produce the PRD
2. prd-to-issues to split the PRD into runnable GitHub issues with priority and dependency metadata

. . . .... 3. Checkout flow

  ftt checkout
	  |
	  v
  +-----------------------+
  | resolve active task   |
  +-----------------------+
	  |
	  v
  +-----------------------+
  | load mapped repos     |
  +-----------------------+
	  |
	  v
  +-----------------------+
  | validate repo paths   |
  | git state + PRDs      |
  +-----------------------+
	  |
	  v
  +-----------------------+
  | move task to          |
  | IN_PROGRESS           |
  +-----------------------+
	  |
	  v
  +-----------------------+
  | wait for target       |
  | branches              |
  +-----------------------+
	  |
	  v
  +-----------------------+
  | start Nexus           |
  | orchestration         |
  +-----------------------+

When you run ftt checkout, the CLI:

1. Resolves the selected task from the current workspace
2. Loads the locally mapped repositories for that task
3. Verifies each mapped path exists, is a git repository, and has a clean working tree
4. Validates that each linked repository has an unambiguous PRD for the task
5. Moves the task to IN_PROGRESS when needed
6. Polls execution stages until the target branches are available
7. Starts Nexus to execute the agent pipeline against the recovered branches

. . . .... 4. Nexus orchestration

Nexus lives under .fiftthnexus/ and is started by ftt checkout after branch recovery.

At runtime, Nexus:

1. Uses gh auth from the host machine for GitHub access
2. Ensures required GitHub labels exist in each repository
3. Builds the copilot-agent Docker image automatically if it is missing
4. Resolves the issue dependency graph for the selected PRD or task scope
5. Creates isolated worktrees when worktree mode is enabled
6. Runs the three-stage pipeline for each runnable issue in Docker
7. Repeats until there are no runnable issues left or the queue is exhausted

The three execution stages are:

• PLAN: analyze the issue context and produce an execution plan
• IMPLEMENT: apply the code changes in the isolated workspace
• REVIEW: run a lightweight final review pass focused on concrete blockers

Requirements

• Node.js 18 or newer
• Git available in your shell
• Docker available locally for checkout and Nexus execution
• GitHub CLI (gh) authenticated for repositories that will run Nexus

Install

npm install -g @fiftth/fiftth-cli

Local development link

npm install
npm run build
npm link

After linking, both commands should work:

fiftth --help
ftt --help

To remove the global development link later:

npm run unlink

Quick Start

1. Authenticate with Fiftth

fiftth login

For CI or non-interactive shells, you can pass a token directly:

fiftth login --token <token>

2. Choose a workspace

fiftth use

You can also switch directly by slug or name:

fiftth use my-workspace

3. Choose the default model used by checkout and Nexus

fiftth model

Or set it directly:

fiftth model gpt-5.4

4. Install the bundled planning skills for your preferred agent runtime

fiftth skills

This command prompts you to install write-prd and prd-to-issues into one of these user directories:

The files are installed relative to the directory where you run the command:

• GitHub Copilot: ./.github/agents
• Claude Code: ./claude/skills

5. Register the local repositories used by your task-linked execution flow

fiftth repo add api ~/dev/api
fiftth repo add mobile C:\Users\you\Desktop\Owner\repo

6. If you are about to create or refine a PRD from inside a repository, validate planning context first

fiftth planning-context

7. Run checkout from any directory to start the orchestration flow

fiftth checkout

To target a specific task directly:

fiftth checkout <taskId>

To keep the main repository checkout untouched and let Nexus branch from a worktree instead:

fiftth checkout --worktree

To stream verbose Nexus logs during checkout:

fiftth checkout --verbose

8. If you need to verify GitHub authentication for Nexus on the host machine

gh auth status

Commands

General

• fiftth --help
• fiftth --version
• fiftth config
• fiftth model
• fiftth model <name>
• fiftth skills
• fiftth skills <agent>

Authentication

• fiftth login
• fiftth login --token <token>
• fiftth login --host <host>
• fiftth login status
• fiftth login logout

To use fiftth login --token <token>, you must first sign in on the Fiftth and generate your token there.

Workspace

• fiftth use
• fiftth use <workspace>

Repository Registry

• fiftth repo add <repoName> <path...>
• fiftth repo list
• fiftth repo remove <repoName>

Tasks and Checkout

• fiftth planning-context
• fiftth planning-context <taskId>
• fiftth planning-context <taskId> --json
• fiftth checkout
• fiftth checkout <taskId>
• fiftth checkout --worktree
• fiftth checkout --verbose

Configuration

Main CLI configuration is saved to:

• ~/.fiftth/config.json

The file stores the current host, access token, selected workspace, workspace id, and preferred model.

Current defaults:

• Host: https://www.fiftth.com/api
• Model: gpt-5.4

Supported model values:

• gpt-5.4
• gpt-5.4-mini
• gpt-5.3-codex
• claude-sonnet-4.6
• claude-opus-4.6
• claude-haiku-4.5

To inspect the current resolved shell configuration:

fiftth config

Notes

• checkout requires local repo mappings for linked repositories (fiftth repo add ...)
• checkout requires a clean git working tree in every linked repository
• checkout requires Docker available on the host machine
• checkout --verbose keeps the normal preflight and then streams detailed Nexus logs once orchestration starts
• planning-context is the safe preflight for skills and manual planning flows: it validates that the current git repository is one of the repositories linked to the selected task and exits non-zero when it is not
• planning-context is the command that depends on the current directory being a git repository; checkout does not have that requirement
• if no taskId is provided, checkout prompts for an active task interactively
• with checkout --worktree, the CLI fetches the target branches, cleans up previous Nexus worktrees for the task, and leaves the main repo checkout unchanged before starting Nexus
• after local checkout succeeds, checkout moves the task to IN_PROGRESS, polls /api/tasks/:taskId/execution-stages every 5 seconds, and starts Nexus once the target branches are available
• planning-context --json is intended for agent and automation flows and exits with code 1 when the current repository is not part of the selected task
• the orchestrator uses the host gh authentication state and injects that token into each isolated agent container

License

MIT