Idea1 CLI

CLI tool for Idea1.ai workflow automation - AI-assisted development workflows.

Installation

npm install -g @idea1/cli

Usage

Headless Mode

Run commands directly from the command line:

# Start implementing a project item
idea1 start-project-item https://app.idea1.ai/project/items/590
idea1 -s https://app.idea1.ai/project/items/590

# Workflow transitions
idea1 start-dev-implementation  # or: idea1 dev
idea1 ready-for-approval john   # or: idea1 rfa john
idea1 approve-pr                # or: idea1 approve
idea1 next-workflow-step        # or: idea1 next

# Show help
idea1 --help

Interactive Mode

Run idea1 without arguments to enter interactive mode with a searchable command interface.

Commands

Workflow Commands

The CLI provides a complete workflow automation system with state tracking. The workflow progresses through these states:

Agent Implementation → Dev Implementation → Needs Approval for Release → Approved and Merged

These are the CLI-driven stages of the full team workflow sequence: Build Spec in Progress → Refinement - Build Spec → Refinement - Implementation → Ready for Agent Implementation → Agent Implementation → Dev Implementation → Needs Approval for Release → Approved and Merged → Released. The earlier states happen in idea1.ai before implementation starts, and Released is set by GitHub automation when the work merges to main.

start-project-item

Start implementing an Idea1.ai project item, either in an isolated git worktree or directly in the main repository.

idea1 start-project-item <url> [branch-name] [options]
idea1 -s <url> [branch-name] [options]

Arguments:

• <url> - The Idea1.ai project item URL (required)
• [branch-name] - Custom branch name (optional, auto-generated from item description if not provided)

Options:

• -p, --source-path <path> - Path to source directory
• -b, --base-branch <branch> - Base branch (default: working/release). Use prompt to interactively select.
• -pm, --permission-mode <mode> - Claude permission mode (default: plan). Valid values: acceptEdits, bypassPermissions, default, delegate, dontAsk, plan
• -iso, --isolation <mode> - Where to work on the branch (default: worktree). See Isolation mode.
• --claude-entry-point <mode> - How Claude is invoked after setup (default: launch). Valid values: launch (start a new Claude session), inline (output structured prompt for an already-running Claude session), none (do not invoke Claude)

What it does:

1. Sets the item's workflow status to "Agent Implementation"
2. Generates a branch name from the item description (if not provided)
3. Creates a new branch from the base branch
4. Sets up the working environment: a git worktree for isolated development, or the branch checked out in the main repository
5. Runs any setup hooks defined in .idea1/settings.json (worktree mode only)
6. Launches Claude Code with the implementation prompt

Isolation mode

start-project-item and join-project-item both ask where you want to work on the branch. The prompt is always shown, with worktree preselected:

• worktree (default) - creates/uses a git worktree in a sibling directory (<repo>-<branch>), leaving the main repository on its own branch. Runs the setup-worktree hook.
• main-repo - checks the branch out in the main repository, in place. Requires a clean working directory and fails if the branch is already checked out in a worktree. The setup-worktree hook is skipped, since the main repository is already set up.

Supply -iso worktree or -iso main-repo on the command line to skip the prompt. The preselected default comes from the defaultIsolationMode user config value.

join-project-item

Join an in-progress project item by setting up a working environment on its existing branch — for picking up work started elsewhere (e.g. on another machine or by another developer). Unlike start-project-item, it does not create a branch or launch a Claude implementation session.

idea1 join-project-item --project-item-url <url>
idea1 join-project-item --branch-name <branch>
idea1 -j --branch-name <branch>

Options (exactly one of the first two must be supplied — they are mutually exclusive):

• --project-item-url <url> - The Idea1.ai project item URL; its branch is discovered automatically.
• -n, --branch-name <branch> - The branch to join; its associated project item is discovered automatically.
• -p, --source-path <path> - Path to source directory.
• -iso, --isolation <mode> - Where to work on the branch (default: worktree). See Isolation mode.
• -pm, --permission-mode <mode> - Claude permission mode (default: plan).
• -e, --effort <level> - Claude effort level (default: high).

In interactive mode, if neither option is supplied you are prompted to choose which to use.

What it does:

1. Resolves the branch from the URL (or the URL from the branch) using the committed branch metadata.
2. Sets up the working environment on the existing branch — a git worktree, or the branch checked out in the main repository (creating a local tracking branch if it only exists on the remote).
3. Re-establishes local workflow state (project item URL, base branch, workflow state, dev workflow type, stack/integration branch) from the committed .idea1/<branch>.json metadata.
4. If the branch was never properly set up, seeds the same defaults as start-project-item (Agent Implementation / independent) and pushes the recovered metadata to the remote.
5. Runs any setup hooks defined in .idea1/settings.json (worktree mode only). It does not launch a Claude implementation session.

If a project item URL is supplied but no branch exists for it yet (the item was never started), join-project-item falls back to the start-project-item setup flow, without launching the implementation session.

attach-project-item

Attach the current branch to a project item, wiring it up as if the branch had been created by start-project-item. Use this when you already have a branch with work on it and want to bring it into the workflow. Unlike start-project-item, it does not create a branch or a worktree and never invokes Claude.

idea1 attach-project-item --url <url>
idea1 attach-project-item                 # prompts for the URL (blank to create a new item)
idea1 -a --url <url>

Options:

• --url <url> - The Idea1.ai project item URL. Leave blank to create a new item (you'll be prompted for a --title).
• -t, --title <title> - Title for the new project item (only when no URL is given).
• -p, --source-path <path> - Path to source directory.
• -b, --base-branch <branch> - Base branch / PR target for an independent feature (default: working/release).
• -w, --workflow-type <type> - Development workflow type: independent or integration. As with start-project-item, you choose any stack branch and (for integration) the integration branch.

What it does:

1. Verifies the current branch is not already attached to a project item (errors if it is — use join-project-item to resume instead).
2. Creates the project item if no URL was supplied.
3. Lets you choose a stack branch and, for integration work, the integration branch — exactly like start-project-item.
4. Sets the item's workflow status to "Agent Implementation".
5. Records the per-branch metadata (project item URL, base branch, workflow state, dev workflow type, stack/integration branch) in git config and the committed .idea1/<branch>.json file.
6. Commits the metadata and pushes the current branch so it is up to date with its metadata.
7. Sets up a PR into the base branch (the integration branch for integration work), just like start-project-item targets it.

start-dev-implementation

Transition from agent implementation to dev implementation - commits, pushes, and creates PR.

idea1 start-dev-implementation [options]
idea1 dev [options]

Options:

• -p, --source-path <path> - Path to worktree directory

What it does:

1. Validates current state is "Agent Implementation"
2. Commits and pushes all changes in the branch
3. Creates a PR of the branch into its base branch
4. If in a worktree and removeWorktreeAtState is set to Dev Implementation, removes the worktree and checks the branch out in the main repo
5. Updates workflow state to "Dev Implementation"
6. Updates Idea1.ai workflow status

ready-for-approval

Mark a PR as ready for approval and optionally assign a reviewer.

idea1 ready-for-approval [reviewer] [options]
idea1 rfa [reviewer] [options]

Arguments:

• [reviewer] - GitHub username of reviewer (optional)

Options:

• -r, --reviewer <username> - GitHub username of reviewer

What it does:

1. Validates current state is "Dev Implementation"
2. Ensures no uncommitted or unpushed changes
3. Assigns reviewer to the PR (if provided)
4. Updates workflow state to "Needs Approval for Release"
5. Updates Idea1.ai workflow status
6. If in a worktree and removeWorktreeAtState is Needs Approval for Release (the default) or earlier, removes the worktree and checks the branch out in the main repo

approve-pr

Approve and merge a PR, completing the workflow.

idea1 approve-pr [options]
idea1 approve [options]

Options:

• -c, --comment <message> - Custom approval comment (default: "Approved via idea1 CLI workflow")

What it does:

1. Validates current state is "Needs Approval for Release"
2. Checks if PR is already approved (skips approval if so)
3. Approves the PR with comment
4. Merges the PR
5. Updates workflow state to "Approved and Merged"
6. Updates Idea1.ai workflow status
7. Switches to base branch and deletes the feature branch. If still running inside a worktree, removes the worktree instead of switching branches — this always happens, since the base branch can't be checked out in place there

next-workflow-step

Automatically perform the next workflow transition based on current state.

idea1 next-workflow-step
idea1 next
idea1 n

What it does:

1. Detects current workflow state
2. Determines the next valid transition
3. Executes the appropriate command automatically
4. If workflow is complete, informs user

Configuration

Configuration Hierarchy

Settings are resolved in order of priority:

1. CLI argument (highest priority)
2. User-level XDG config (~/.config/idea1-cli/config.json)
3. Repository-level .idea1/settings.local.json (git-ignored, per-clone overrides)
4. Repository-level .idea1/settings.json
5. Hardcoded defaults (lowest priority)

Repository Settings

Create .idea1/settings.json in your repository root to configure repo-specific settings.

{
  "hooks": {
    "setup-worktree": "dev/workflow/setup-worktree.sh"
  },
  "defaults": {
    "branchPrefix": "working/agent",
    "baseBranch": "working/release",
    "testCommand": "npm run test"
  }
}

Hooks:

• setup-worktree - Script to run after creating a new worktree (e.g., install dependencies)

Defaults:

• branchPrefix - Prefix for new branches (default: working/agent)
• baseBranch - Default base branch for branching (default: working/release)
• testCommand - Command to run tests before PR creation (e.g., npm run test)
• removeWorktreeAtState - Workflow state whose transition removes the worktree (default: Needs Approval for Release). See Worktree Removal.

Local Settings Overrides

.idea1/settings.local.json is an optional, git-ignored file with the same shape as settings.json. Anything it defines overrides the committed settings for that clone only, which keeps developer-specific preferences out of the shared configuration. hooks and defaults are merged section by section, so overriding one value leaves the rest of the committed settings in place.

{
  "defaults": {
    "removeWorktreeAtState": "Dev Implementation"
  }
}

Worktree Removal

When work happens in a git worktree, removeWorktreeAtState decides which workflow transition tears that worktree down. The worktree is removed by the first transition that reaches the configured state, and the branch is then checked out in the main repo.

| Value | Worktree is removed by | |-------|------------------------| | Dev Implementation | start-dev-implementation — right after the PR is created | | Needs Approval for Release (default) | ready-for-approval | | Approved and Merged | approve-pr, after the PR is merged |

approve-pr removes the worktree regardless of this setting if one is still in use, because the base branch can't be checked out in place there. close-worktree is an explicit teardown command and always removes the worktree.

User Settings

User settings are stored in the XDG-compliant config directory:

• macOS: ~/Library/Preferences/idea1-cli/
• Linux: ~/.config/idea1-cli/
• Windows: %APPDATA%/idea1-cli/

Settings include:

• defaultBaseBranch - Default base branch (default: working/release)
• defaultBranchPrefix - Default branch prefix (default: working/agent)
• defaultIsolationMode - Default isolation mode (default: worktree)

Requirements

• Node.js 20+
• Git
• GitHub CLI (gh) - for PR operations
• Claude Code CLI (claude) - for AI-assisted development

Development

# Build the CLI
npm run build

# Run directly from the local source code
npm run start

# Link globally for testing
npm link

# Install the CLI from the latest published idea1 command package
npm install -g @idea1/cli

# Run the CLI from the current installed idea1 command package
idea1 --help