---
title: "alis setup"
url: "https://docs.alisx.com/reference/cli/setup/"
---
# alis setup

Set up and repair the local Alis Build development environment: the same engine behind the TUI's Setup screen, as deterministic commands that a coding agent can drive.

## Synopsis

```bash
alis setup complete [flags]
alis setup install [<step name>...] [flags]
alis setup path [flags]
alis setup profile [flags]
alis setup quickstart [flags]
alis setup status [flags]
```

## Description

The loop for an agent: call `alis setup status --json`, act on the single instruction under `.next`, and repeat until `.ready` is true. `next.kind` is `run` (run `next.command`, then call `status` again), `ask_user` (relay `next.agent` to the human, wait, then call `status` again) or `done`.

The ladder `status` walks down: PATH, login, tools, account, profile, record.

## Subcommands

### alis setup complete

Record on the user's build profile that this machine is set up, optionally recording the coding agents that were installed. Idempotent.

```bash
alis setup complete [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--harness <name>` | stringArray | | Coding agent installed on this machine (repeatable): `antigravity`, `claude-app`, `claude-code`, `codex`, `codex-app`, `cursor`, `gemini`, `opencode`. |

### alis setup install

Run the runnable steps from the setup plan, the same installs the TUI's Setup screen performs. Interactive steps (for example Homebrew's sudo prompt) and manual steps are never attempted: they are returned under `needs_user` for the agent to hand to the human. With no arguments and no `--all`, nothing runs.

```bash
alis setup install [<step name>...] [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all` | bool | false | Install every missing runnable step. |

### alis setup path

Write the `alis` PATH block into the shell rc files for the user's shell, creating missing files and replacing any previous block. This is the repair for "command not found: alis" after an install: the installer's rc edit never affects already-open shells. The current shell is never modified; open a new terminal or run the printed `source_command`. On Windows the user PATH in the registry is written instead.

```bash
alis setup path [flags]
```

No flags beyond the global flags.

### alis setup profile

Record build-profile choices from the machine being set up, so a coding agent can complete the profile without the console. Only the flags you pass are written: providers and coding agents are union-merged (a provider covers its full bundle: CLI, desktop app and the Alis Build plugin); `--ide` replaces the IDE list, first entry primary. Everything stays editable at `https://console.alisx.com/build/profile`.

```bash
alis setup profile [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--experience <level>` | string | | `advanced`, `beginner`, `expert` or `intermediate`. |
| `--harness <name>` | stringArray | | Coding agent to record (repeatable): `antigravity`, `claude-app`, `claude-code`, `codex`, `codex-app`, `cursor`, `gemini`, `opencode`. |
| `--ide <name>` | stringArray | | IDE to record, first is primary (repeatable): `antigravity`, `cursor`, `neovim`, `vim`, `vscode`. |
| `--os <name>` | string | | Deprecated and ignored; the operating system is detected. |
| `--provider <name>` | stringArray | | AI provider to record, covering its full bundle (repeatable): `antigravity`, `claude`, `codex`, `cursor`, `opencode`. |

### alis setup quickstart

List the curated quickstart scenarios for a freshly set-up builder. Load the chosen one with its `load_command`; the loaded skill owns execution from there.

```bash
alis setup quickstart [flags]
```

No flags beyond the global flags.

### alis setup status

Report machine state and the single next action.

```bash
alis setup status [flags]
```

No flags beyond the global flags.

## Examples

```bash title="Terminal"
alis setup status --json
alis setup path --json
alis setup install --all --json
alis setup install git --json
alis setup profile --harness claude-code --ide vscode --experience beginner --json
alis setup complete --harness claude-code --json
alis setup quickstart --json
```

## JSON output

`status --json`:

```json
{
  "ready": true,
  "environment": "local",
  "cli_version": "<version>",
  "path": "ok",
  "shell": "zsh",
  "restart_terminal": false,
  "signed_in": true,
  "build_account": "accounts/<id>",
  "profile_loaded": true,
  "local_setup_complete": true,
  "steps": [
    {"name": "git", "installed": true, "detail": "/opt/homebrew/bin/git", "command": "brew install git"},
    {"name": "Claude Code (Alis Build Plugin)", "installed": true, "command": "…"}
  ],
  "next": {"kind": "done", "command": "alis setup quickstart --json", "agent": "Setup is complete. List the quickstarts and let the user pick one."}
}
```

`environment` is `local`, `browser_shell` (an Alis workstation) or `build_workstation`. `restart_terminal: true` means installed tools reach the user's own shell only in a new terminal (or through `path_refresh_command`). `install --json` returns each step's outcome; a failed step with a `hint` would fail the same way by hand. `quickstart --json` returns `quickstarts[]` with `id`, `title`, `outcome` and `load_command`.

## Notes

On Windows, Claude Desktop runs commands through Git Bash: install git first (`alis setup install git --json`), then restart the app. winget failures fall back to the publishers' signed installers automatically.