npm package: @fiftth/fiftth-cli
Description: CLI for the Fiftth , start orchestrating your AI engineering workflow
Author: Fiftth
Latest version: 1.1.3

# Fiftth CLI

```text
. . . ....
```

The official CLI for [Fiftth](https://fiftth.com).

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. `grill-me` to pressure-test the design
2. `write-prd` to produce the PRD
3. `prd-to-issues` to split the PRD into runnable GitHub issues with priority and dependency metadata

### . . . .... 3. Checkout flow

```text
  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

```bash
npm install -g @fiftth/fiftth-cli
```

### Local development link

```bash
npm install
npm run build
npm link
```

After linking, both commands should work:

```bash
fiftth --help
ftt --help
```

To remove the global development link later:

```bash
npm run unlink
```

## Quick Start

1. Authenticate with Fiftth

```bash
fiftth login
```

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

```bash
fiftth login --token <token>
```

2. Choose a workspace

```bash
fiftth use
```

You can also switch directly by slug or name:

```bash
fiftth use my-workspace
```

3. Choose the default model used by checkout and Nexus

```bash
fiftth model
```

Or set it directly:

```bash
fiftth model gpt-5.4
```

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

```bash
fiftth skills
```

This command prompts you to install `grill-me`, `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

```bash
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

```bash
fiftth planning-context
```

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

```bash
fiftth checkout
```

To target a specific task directly:

```bash
fiftth checkout <taskId>
```

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

```bash
fiftth checkout --worktree
```

To stream verbose Nexus logs during checkout:

```bash
fiftth checkout --verbose
```

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

```bash
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](https://fiftth.com) 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:

```bash
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