Guided setup: interview, review, apply

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

New to AIWG? Start with Install, connect, verify; this page covers the guided flow once the CLI is installed.

After installing Node.js 24+ and the full `aiwg` package, open a terminal in the intended project. The public installer can handle bootstrap and repair in your provider session. It remains a provider-orchestrated manifest; the agent-owned setup-run operation does not execute it.

Save the interview plan

Use AIWG to complete this documented outcome: Save the interview plan
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Replace `claude` with your provider, or use a comma-separated list such as `claude,codex`. Explicit flags win over saved answers and existing settings. The interview asks about targets, intent, tools, locations, and optional capabilities. It writes a plan beneath the configured AIWG artifact root at `setup/plans/<plan-id>.json`, not provider configuration. The default plan ID is derived from the current workspace. the agent-owned init operation also enters the guided interview; plain the agent-owned setup operation retains repository-policy setup behavior. Include the scope option to select the guided flow explicitly.

Use `back` to revisit a question or `edit <question-id>` for an answered question. Change an explicit flag to edit its answer. `skip` leaves an optional choice unanswered; `defer` prioritizes it on resume. `cancel` leaves the last saved plan intact; answers since the last saved question block may be lost. Run the interview again to continue. Existing settings are preserved unless explicitly changed; the force option starts the interview answers again.

The scope flag controls provider deployment: `project` targets project files; `user` targets the provider's user configuration. Project policy and registry writes still use their own owners. This is separate from globally installing the CLI with npm, and from the direct deployment command's global mode.

Review, then apply

Use AIWG to complete this documented outcome: Review, then apply
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Review groups actions by workspace and provider and reports conflicts, stale facts, and missing credential references without writing anything. With a saved plan, a bare the agent-owned setup operation is also a review. With interview flags, the dry-run option previews an interview without saving it. `the review option the json option` emits the review report; `the apply option the json option` emits `aiwg.setup.apply.v1`. Use `the plan option <id>` on review/apply to select another saved plan, and `the target option <dir>` to identify the project that owns it.

Apply asks for confirmation, invokes the existing owners, and saves receipts after each action. Usage intent chooses the framework: `code` and `mixed` use SDLC, `docs` uses writing, and `ops` uses ops. Direct complete-system deployment remains available through the agent-owned use operation.

The apply report distinguishes `success`, `partial` (core ready, optional actions failed or skipped), and `failure` (core actions failed or skipped). Partial and failed results return a nonzero exit code. Inspect the action messages before claiming readiness. A successful repeat apply is a no-op; partial and interrupted runs retry only unfinished actions. A crash between an owner's external side effect and its saved receipt requires checking that owner before retrying. Changed environment facts are refused: rerun discovery through the interview and review the new plan rather than forcing stale actions.

Headless answers use the same flow

Use AIWG to complete this documented outcome: Headless answers use the same flow
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Headless mode never prompts. Required unanswered choices fail with the flag to supply; optional integrations stay off when unanswered. Apply requires the yes option when no interactive confirmation is available. The example records a plan; a provider configuration action without a credential reference can remain skipped until you supply its reference and rerun the interview.

Credential flags store locators only. Supply the named environment variable securely in the apply process, or use an absolute file reference or redirected stdin. Do not paste a token into an argument or plan. For example:

Use AIWG to complete this documented outcome: Credential flags store locators only. Supply the named environment variable securely in the apply process, or use an absolute file reference or redirected stdin. Do not paste a token into an argument or plan. For example
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

`the credential option claude=file:/absolute/path` references a file; `the credential option claude=stdin` defers input until apply. The interview and review never resolve credential bytes.

Multiple roots and monorepos

Discovery starts with the current workspace and registered roots. Additional scanning requires explicit opt-in; it is bounded and refuses home/filesystem roots. Use `the scan-roots option <dir>` to observe another root and repeat `the workspace option <root>` to select observed roots. Selection of a monorepo root or package must be explicit in headless mode:

Use AIWG to complete this documented outcome: Discovery starts with the current workspace and registered roots. Additional scanning requires explicit opt-in; it is bounded and refuses home/filesystem roots. Use the scan-roots option <dir to observe another root and repeat the workspace option <root to s
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The package must be an observed package root. Review project/user scope conflicts and provider destinations before applying; a scope switch does not authorize replacing existing files.

Optional integrations

Jev sends decisions to an external service and requires an account/API access; usage charges apply. Enable it explicitly with a reference:

Use AIWG to complete this documented outcome: Jev sends decisions to an external service and requires an account/API access; usage charges apply. Enable it explicitly with a reference
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

`the jev option decline` leaves it off; `the jev option defer` leaves the choice unresolved. Existing Jev options include `the region option <r>`, `the endpoint option <https-url>`, the token-stdin option, the verify option, and the remove option. Verification can send a billable request at apply; no network probe runs in the interview. Removal is explicit and cannot be combined with enable options.

Use AIWG to complete this documented outcome: the jev option decline leaves it off; the jev option defer leaves the choice unresolved. Existing Jev options include the region option <r, the endpoint option <https-url, the token-stdin option, the verify option, and the remove option. Verification can send a billable request at apply; no network pro
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Direct workers use their own accounts' quota. Installing a worker CLI does not qualify it: apply delegates to worker setup and doctor qualification, and launch checks availability again. Configure worker paths, groups, and limits through the existing parallelism configuration. Worker qualification or Jev failures are reported separately so core readiness remains visible. See worker dispatch for account and qualification details.