FishLadder CLI — Documentation

Getting started

Requirements: Node.js 18 or higher.

1

Install

Install the CLI globally via npm.

npm install -g fishladder

Login

1

Authenticate

Opens your browser to authenticate with your FishLadder account.

2

Approve in browser

Once you approve, your session is stored securely in your system keychain. No credentials are written to disk.

3

Verify

Run fish whoami to confirm everything is working.

# Authenticate via browser
fish login

# Confirm your session
fish whoami

Auth commands

fish login                # Authenticate via browser
fish login --team <id>    # Mint a key for a specific team
fish logout               # Remove stored keys (or one team with --team)
fish whoami               # Show current user, team, and access

Teams

A key belongs to exactly one team. If you belong to several, list them and switch between them:

# List your teams — the active one is marked
fish teams list

# Point subsequent commands at a team you already have a key for
fish teams use <teamId>

# Get a key for a team you don't have one for yet
fish login --team <teamId>

💡 Set FISHLADDER_TEAM to pin one terminal to a team without disturbing your other sessions.

Projects

Manage roadmap projects in your workspace.

fish projects list
fish projects list --format json
fish projects create "Mobile app v2"
fish projects update <id>
fish projects delete <id>

Default project

Set a default project for the current directory so fish tasks commands don't need --project every time. The choice is saved to .fishladder.json.

fish project use <nameOrId>   # Set (by ID, name, or unique fragment)
fish project current          # Show the default in effect
fish project clear            # Clear it

Tasks

# List tasks (filters by the default project when one is set)
fish tasks list
fish tasks list --project <id>
fish tasks list --all
fish tasks list --format json

# Create a task — smart syntax is parsed out of the title
fish tasks create "Fix auth bug @sarah !high #backend due:friday"
fish tasks create "Fix auth bug" --project <id> --assign <userId> --priority high --due 2026-04-01

# Work with existing tasks
fish tasks show <id>
fish tasks update <id>
fish tasks complete <id>
fish tasks delete <id>

# List tracker projects (boards)
fish tasks projects

Smart syntax

Token	Meaning
@user	Assignee
!priority	Priority level
#tag	Label
due:date	Due date

List options

Flag	Description
--project <id>	Filter by project ID
--all	List tasks across all projects, ignoring the default project
--format json	Output as JSON

Create options

Flag	Description
--project <id>	Project to add the task to (defaults to the project set via `fish project use`)
--description <text>	Task description
--section <idOrName>	Board column to place the task in
--assign <userId>	Assign to a team member
--priority <level>	`none` / `low` / `medium` / `high` / `urgent`
--due <YYYY-MM-DD>	Due date

💡 Set a default project once with fish project use and every task command in that directory picks it up automatically.

Feedback

# List feedback
fish feedback list
fish feedback list --format json

# Create feedback
fish feedback create "Customers want dark mode"
fish feedback create "Customers want dark mode" --details "..." --impact high --company Acme

# AI analysis — pass IDs, or pipe text in via stdin
fish feedback analyze --ids <id1,id2>
fish feedback analyze < q3-interviews.txt

Create options

Flag	Description
--details <text>	Full description of the feedback
--impact <level>	`low` / `medium` / `high` (default: medium)
--company <name>	Company the feedback came from

Analyze options

Flag	Description
--ids <ids>	Comma-separated feedback IDs to analyze
--format json	Output as JSON

Hiring

# List open roles
fish hiring jobs
fish hiring jobs --format json

# List candidates
fish hiring candidates
fish hiring candidates --format json

# View pipeline
fish hiring pipeline
fish hiring pipeline --job <id>
fish hiring pipeline --format json

# Move candidates through the pipeline
fish hiring move <applicationId>
fish hiring hire <applicationId>
fish hiring reject <applicationId>

Pipeline options

Flag	Description
--job <id>	Filter pipeline by job ID
--format json	Output as JSON — pipeable to `jq`

More commands

The CLI covers every FishLadder module. Run fish <command> --help for the full reference on each:

Command	What it manages
fish goals	Goals and OKRs
fish initiatives	Roadmap initiatives
fish rows	Kanban rows
fish sections	Board sections (columns) of a tracker project
fish statuses	Workflow statuses of a tracker project
fish custom-fields	Custom field definitions
fish webhooks	Webhook endpoints
fish ai	AI-powered analysis and suggestions
fish crm	CRM: contacts, companies, deals, pipelines, activities
fish cpq	CPQ: products, quotes, line items
fish river	River wiki spaces and pages

JSON output

Every command supports --format json for scripting and piping to jq (table output is the default).

# Count active candidates
fish hiring candidates --format json | jq 'length'

# Get all task titles
fish tasks list --project <id> --format json | jq '.[].title'

# Filter open jobs
fish hiring jobs --format json | jq '.[] | select(.status == "open")'

Environment variables

Variable	Description
FISHLADDER_API_KEY	Use a specific API key instead of the stored session. Useful for CI/CD.
FISHLADDER_TEAM	Pin this terminal to a specific team without disturbing other sessions.
FISHLADDER_API_URL	Override the API base URL. Defaults to `https://app.ladder.fish/api/v1`.
FISHLADDER_AUTH_URL	Override the auth base URL. Defaults to `https://app.ladder.fish`.

Revoking access

Tokens created by fish login appear in your FishLadder workspace under Settings → API Keys. You can revoke them from there at any time.

To log out from the CLI:

fish logout

Troubleshooting

fish: command not found

Your npm global bin directory isn't in your PATH. Run npm bin -g to find it, then add it to your shell config (e.g. ~/.zshrc).

Not logged in

Run fish login to authenticate. If login completes but commands still fail, your system keychain may not be accessible — set FISHLADDER_API_KEY as a fallback.

Rate limit exceeded

The API allows 120 requests per hour. The CLI will tell you how long to wait. If you're hitting this regularly, use --format json to cache results locally.

401 Unauthorized

Your session has expired or been revoked. Run fish login again.

Browser doesn't open during login

The CLI will print the auth URL in the terminal. Copy and paste it into your browser manually to complete login.

Still stuck? Email [email protected]