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:

# Put a project item under workflow management (branch + metadata, no code changes)
idea1 start --url https://app.idea1.ai/project/items/590

# Advance the item to its next workflow state (runs that state's automation)
idea1 next --url https://app.idea1.ai/project/items/590   # or just `idea1 next` on the item's branch

# Jump straight to Agent Implementation (worktree + Claude) — the "send for implementation" path
idea1 start-agent-implementation --url https://app.idea1.ai/project/items/590   # alias: start-project-item

# Dedicated transitions (each is one `next` step)
idea1 start-dev-implementation  # or: idea1 dev
idea1 ready-for-approval        # or: idea1 rfa
idea1 approve-pr                # or: idea1 approve

# Carry an integration branch into working/release (opens the PR, assigns its approver; the assignee merges it)
idea1 integrate                 # or: idea1 int

# Release the release branch to production (opens the release PR into main, assigned to you, and merges it once the checks pass)
idea1 release                   # or: idea1 r

# Show help
idea1 --help

Interactive Mode

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

Commands

Workflow Commands

Every project item moves through the same sequence of workflow states:

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 state names and their order are defined once, in shared-config/workflow-states.json, and shared with the backend and the web client (see scripts/generate-workflow-states.js).

How the workflow engine works

An item under workflow management has exactly one branch on origin that carries .idea1/<branch>.json with the item's URL and current workflowState. That committed file is the durable, shared record: the idea1.ai web client writes the same file when a state is advanced from the browser, and every CLI command first syncs the branch's state from origin (adopting the metadata into local git config and fast-forwarding a local checkout when it is behind) — so the CLI and the web client never disagree.

A transition is "enter state X". Entering a state runs that state's automation (a handler), then records the new state in the branch metadata, in local git config and on the idea1.ai item. Most states have no automation; the implementation states do:

| Entering | Automation | |----------|-----------| | Build Spec in Progress … Ready for Agent Implementation | none — status only | | Agent Implementation | ensures the branch is checked out locally (worktree or main repo), then launches Claude to implement the item. This is the only transition that starts code-writing automation | | Dev Implementation | commits and pushes the agent's work, creates the PR, removes the worktree if removeWorktreeAtState says so | | Needs Approval for Release | requires the PR, sets its assignee (required — the approver of record) and any requested reviewers, removes the worktree if configured | | Approved and Merged | verifies you are the assignee, removes the metadata file, waits for the CI/CD suite, merges the PR — the merge is the approval — then deletes the branch and worktree | | Released | none — normally set by GitHub automation when the work merges to main |

start begins state management, next advances one state, and start-agent-implementation jumps to Agent Implementation — all three reduce to the same engine, so branches and items always end up consistent with the state they are in.

Who approves what

A change reaches production through two merges, and each merge is its approval.

Into working/release — the PR's assignee (required) is its approver. They review the code and approve it by running idea1 approve-pr, which waits for the full CI/CD suite and then merges the PR. That is not the GitHub "Approve" button, which only leaves a review behind and merges nothing. A red or unfinished suite stops the merge, and there is no override at this stage. approve-pr checks that the person merging is the assignee; anyone else has to confirm explicitly, and the evidence report lists that merge as an exception. Requested reviewers are optional and record nothing. GitHub records the approval as merged_by, with its timestamp and merge commit.

Integration branches into working/release — work items for an integration PR into working/integration/<name>-main and are approved there exactly as above. The integration branch itself enters working/release through idea1 integrate: it opens the PR with the approval chain of the work items it carries and assigns its approver; the assignee merges it (idea1 integrate --pr-mode merge) once the suite passes — the same sequence as a release, including the recorded admin override.

Into main — idea1 release opens the release PR assigned to whoever ran it: the releaser is the approver, and their merge is the recorded approval. No review is required — every change in the release was already approved above, and the release PR body lists each contained PR with who approved it. What this stage gates is the build: the required CI/CD checks must pass first. In the default create mode the releaser merges the PR in GitHub once the checks are green; in merge mode the CLI waits for every check with gh and merges here. An emergency admin override past a red check needs an explicit confirmation and a stated reason, and is recorded as a comment on the PR before the merge.

This is the change-management control DataFabrIQ is audited on; see infrastructure/soc2/policies/change-management-policy.md clause 2.

start

Put a project item under workflow management. An item that has never been started enters Build Spec in Progress; an item that already has a state keeps it. The branch is created on origin from the base branch with the metadata file as its first commit — nothing is checked out, no code is written and Claude is not launched. Idempotent: running it again for a managed item just reports the branch and state.

idea1 start --url <url> [options]
idea1 start                       # prompts for the URL (blank to create a new item)
idea1 s --url <url>

Options:

• -u, --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.
• -n, --branch-name <name> - Branch name (auto-generated from the item description if not provided).
• -b, --base-branch <branch> - Base branch / PR target (default: working/release).
• -w, --workflow-type <type> - independent or integration; you also choose any stack branch and (for integration) the integration branch.

next-workflow-step

Advance a project item to its next workflow state and run that state's automation. On the item's branch no arguments are needed; from anywhere else pass the item URL — the CLI finds the branch on origin (moving into its local checkout when one exists) or, for an item without a branch yet, reads the current state from idea1.ai and creates the branch first.

With --to <state> the item advances through every state up to that one in a single run — the same as running next once per state, with each state's automation in order. The CLI only moves forward; an item already at or past the requested state is reported as an error.

idea1 next                        # on the item's branch
idea1 next --url <url>            # from anywhere in the repository
idea1 next --to "Dev Implementation"   # several states at once
idea1 n

Options:

• -u, --url <url> - Project item URL (required when not on the item's branch).
• --to <state> - Workflow state to advance to (default: the next state).
• -p, --source-path <path> - Path to source directory.
• Any option of the state being entered (for example --model/--effort for Agent Implementation, --assignee/--reviewers for Needs Approval for Release). Options that were not supplied are prompted for when that state is reached.

What it does:

1. Syncs the branch's workflow state from origin (picking up changes made in the web client).
2. Puts the item under workflow management if it is not yet (a never-started item enters Build Spec in Progress, which is the whole step).
3. Runs the automation of every state entered, records the new state on the branch, in git config and on idea1.ai.
4. Reports "Workflow is complete" at Released.

The automation is idempotent, so re-running a transition after the item was moved back in the web client does not repeat work that is already done: an existing PR is reused, an already-merged PR is left alone and the item simply moves on.

start-agent-implementation

Start implementing a project item: put it under workflow management if needed, move it to Agent Implementation (through any intermediate states, which have no automation), set up the working environment and launch Claude Code with the implementation prompt (or a prompt you supply — see --entry-point-prompt). This is the command behind "Send for Implementation" in the web client; start-project-item remains an alias so existing team command templates keep working.

idea1 start-agent-implementation --url <url> [options]
idea1 implement --url <url>
idea1 start-project-item --url <url>     # alias
idea1 implement --url <url> --entry-point-prompt "Read the spec in docs/spec.md and implement step 3"

Options: all start options, plus the Agent Implementation options:

• -iso, --isolation <mode> - Where to work on the branch (default: worktree). See Isolation mode.
• -pm, --permission-mode <mode> - Claude permission mode (default: plan). Valid values: acceptEdits, bypassPermissions, default, delegate, dontAsk, plan
• -m, --model <model> - Claude model for the implementation session (default: opus). Valid values: fable, opus, sonnet, haiku
• -e, --effort <level> - Claude effort level (default: high). Valid values: low, medium, high, xhigh, max
• -im, --claude-entry-point <mode> - How Claude is invoked once the environment is ready (default: launch). Valid values: launch (start a new Claude session), inline (output a structured prompt for an already-running Claude session), none (do not invoke Claude)
• -udp, --use-default-prompt <yes|no> - Whether to launch Claude with the default implementation prompt (default: yes). Answering no asks for the prompt to use instead.
• -epp, --entry-point-prompt <prompt> - The prompt to launch Claude with, replacing the default implementation prompt. Supplying it skips the "Use default prompt?" question.

An item already in Agent Implementation is not transitioned again: the working environment is set up (or reused) and Claude is launched.

Isolation mode

start-agent-implementation, next (when entering Agent Implementation) and join-project-item all 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, by another developer, or from the web client). It does not change the workflow state and never launches a Claude implementation session.

idea1 join-project-item --project-item-url <url>
idea1 join-project-item --branch-name <branch>
idea1 join-project-item --pull-request-url <pr url>
idea1 j --branch-name <branch>

Options (exactly one of the first three 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.
• --pull-request-url <url> - A GitHub PR URL; its head branch is joined.
• -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>, -m, --model <model>, -e, --effort <level> - Claude session settings recorded for the environment (defaults: plan, opus, high).

What it does:

1. Resolves the branch from the URL (or the URL from the branch) using the committed branch metadata.
2. Reuses the checkout that already holds the branch, or sets one up — a git worktree, or the branch checked out in the main repository (creating a local tracking branch if it only exists on origin).
3. Syncs the workflow state from the metadata committed on origin into local git config, defaulting a legacy branch with no recorded state to Agent Implementation, and pushes any recovered metadata back to origin.
4. Runs any setup hooks defined in .idea1/settings.json (newly created worktrees only).

If a project item URL is supplied but no branch exists for it yet, join-project-item puts the item under workflow management first (as start does) and then sets up the environment.

attach-project-item

Attach the current branch to a project item, putting it under workflow management at the item's current state (or Build Spec in Progress when it has none). Use this when you already have a branch with work on it and want to bring it into the workflow. 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:

• -u, --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. You also 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, and reads its current workflow state from idea1.ai.
3. 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, and pushes the branch.
4. Records the branch on the idea1.ai item. If the item is already at Dev Implementation or later, makes sure a PR into the base branch exists.

start-dev-implementation

Enter Dev Implementation from Agent Implementation — the same step next takes from that state.

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

Options:

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

What it does:

1. Validates the current state is "Agent Implementation" (after syncing from origin)
2. Commits and pushes all changes in the branch
3. Creates a PR of the branch into its base branch
4. Records "Dev Implementation" in the branch metadata, git config and on Idea1.ai
5. If in a worktree and removeWorktreeAtState is Dev Implementation, removes the worktree. The main repo stays on its current branch; use join-project-item to work on the item in the main repo or a new worktree.

ready-for-approval

Enter Needs Approval for Release from Dev Implementation — the same step next takes from that state. Its job is to name the assignee, who will approve the change by merging it.

idea1 ready-for-approval [options]
idea1 rfa --assignee octocat

Options:

• -a, --assignee <username> - Required. Who approves the PR by merging it (prompted from the repository's assignable users when omitted)
• -r, --reviewers <user1,user2> - Who to request a review from (multi-select when omitted). Optional, and separate from approval — the assignee is the approver

What it does:

1. Validates the current state is "Dev Implementation" (after syncing from origin)
2. Ensures no uncommitted or unpushed changes in the local checkout
3. Requires the PR to exist, then sets the assignee (the transition refuses to proceed without one) and requests any reviewers
4. Records "Needs Approval for Release" in the branch metadata, git config and on Idea1.ai
5. If in a worktree and removeWorktreeAtState is Needs Approval for Release (the default) or earlier, removes the worktree

approve-pr

Enter Approved and Merged from Needs Approval for Release — the same step next takes from that state. Run by the PR's assignee: it waits for the CI/CD suite and merges the PR, and that merge is the approval of record.

idea1 approve-pr
idea1 approve

What it does:

1. Validates the current state is "Needs Approval for Release" (after syncing from origin)
2. Verifies the approver: refuses when the PR has no assignee, and when you are not the assignee warns that the merge record will name you instead and requires an explicit confirmation (the evidence report lists such a merge as an exception)
3. Removes the branch's .idea1/<branch>.json so it does not leak into the target branch, waits for the required CI/CD checks on the PR (that push re-runs the suite), then merges the PR. A red or unfinished suite stops the merge — there is no admin override at this stage
4. Records "Approved and Merged" in git config and on Idea1.ai
5. Switches to the 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

integrate

Carry an integration branch (working/integration/<name>-main) into the release branch. This is stage 1 for integration work: the work items were each approved on their own PR into the integration branch; integrate opens the integration branch's PR into working/release, assigns its approver, and — run by that assignee — merges it once the required CI/CD checks pass. It is not part of the project-item state machine.

idea1 integrate --assignee octocat        # on the integration branch: open the PR and assign its approver
idea1 integrate --pr-mode merge           # run by the assignee: wait for the checks, then merge
idea1 int

Options:

• -b, --branch <branch> - Integration branch to integrate (default: the current branch when it is one, otherwise a pick from the integration branches on origin)
• -t, --target <branch> - Branch to integrate into (default: baseBranch, then working/release)
• -a, --assignee <username> - Who approves the integration by merging its PR (prompted when the PR is created and none is given)
• -pr, --pr-mode <mode> - create (default) opens the PR in the browser to merge there once the checks pass; merge waits for every check with gh and merges here
• --title <title> - PR title (default: Integration <name> <YYYY-MM-DD>)

What it does:

1. Reuses the open PR from the integration branch into the target if one exists; otherwise requires you to be on the integration branch with nothing uncommitted, unpushed or behind origin, and creates the PR assigned to the approver, with the approval chain of the work-item PRs it carries as its body
2. In merge mode, checks that you are the assignee (anyone else must confirm explicitly), waits for the required CI/CD checks and merges. Checks that fail, never start or never finish stop the merge; the admin override takes an explicit confirmation and a required reason, and the exception is recorded as a comment on the PR before anything is merged

release

Release everything on the release branch to production. Opens the release PR from working/release into main, assigned to you, and merges it — the person who runs the command is the releaser and the approver, and no review is required, because every change in the release was already approved on its own PR.

idea1 release                     # prompts for the PR mode and title
idea1 release --pr-mode merge     # wait for the required checks, then merge here
idea1 r

Options:

• -b, --branch <branch> - Source branch to release from (default: releaseBranch, then baseBranch, then working/release)
• -t, --target <branch> - Target branch to release into (default: releaseTargetBranch, then main)
• -pr, --pr-mode <mode> - create (default) creates the PR and opens it in the browser so you merge it there once the required checks pass; merge waits for every check with gh and merges here. The merge is the recorded approval in both
• --title <title> - PR title (default: Release <YYYY-MM-DD>)

What it does:

1. Requires you to be on the release branch with nothing uncommitted, unpushed or behind origin, then runs the pre-release hook (the version bumps). The hook runs before the PR is opened, so its commit is the PR's head and the suite runs once, on the release as it will merge
2. Creates the release PR assigned to you, whose body is the release's approval chain: every contained PR — attributed by GitHub's commit association, so squash and rebase merges are covered — with its author and the assignee who approved it by merging. Commits with no PR are listed separately, split in two: the pre-release hook's version bumps, which are release automation and not an exception, and genuine direct commits, which are
3. Refuses the release when nothing in it came through a merged PR. A repository admin can override that — an explicit confirmation and a required reason — and the exception is recorded as a comment on the PR naming the admin, the reason and every commit that had no PR, as well as in the PR body. Anyone who is not a repository admin just gets the refusal
4. In merge mode, waits for the required CI/CD checks and merges normally. Checks that fail, never start or never finish stop the release; an admin override is available but takes an explicit confirmation and a required reason, and the exception is recorded as a comment on the PR before anything is merged
5. Opens GitHub Actions, where the merge to main has triggered the production deploy

Configuration

Configuration Hierarchy

Settings are resolved in order of priority:

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

Branch names come only from the repository being worked in — nothing machine-global sits above its .idea1/settings.json, so a repo that branches onto draft keeps branching onto draft whatever other repos on the machine use.

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.

| 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:

• defaultIsolationMode - Default isolation mode (default: worktree)

Branch names are not user settings: they belong to the repository and are read from its .idea1/settings.json.

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