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 → PR needs Approval → Complete

start-project-item

Start implementing an Idea1.ai project item in an isolated git worktree.

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
• --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. Creates a git worktree for isolated development
5. Runs any setup hooks defined in .idea1/settings.json
6. Launches Claude Code with the implementation prompt

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 removeWorktreeOnDevTransition is enabled in .idea1/settings.json, removes the worktree
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 "PR needs Approval"
5. Updates Idea1.ai workflow status
6. If in a worktree, removes the worktree

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 "PR needs Approval"
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 "Complete"
6. Updates Idea1.ai workflow status
7. Switches to base branch and deletes the feature branch

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.json
4. 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)
• removeWorktreeOnDevTransition - Whether to remove the worktree when transitioning to dev implementation (default: false). The ready-for-approval transition always removes the worktree if running inside one.

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