npm package: @idea1/cli
Description: CLI tool for Idea1.ai workflow automation - AI-assisted development workflows
Author: Idea1.ai
Latest version: 1.4.6

# Idea1 CLI

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

## Installation

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

## Usage

### Headless Mode

Run commands directly from the command line:

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

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

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

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

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

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

```json
{
  "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

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