# AgentUI CLI (`@agentuiai/cli`)

> Machine-readable reference for the AgentUI command-line tool. If you are an AI
> coding assistant working with AgentUI, this file is the one to read: it is the
> whole command surface in one flat document, no navigation required.

- **Package:** `@agentuiai/cli` — https://www.npmjs.com/package/@agentuiai/cli
- **Source:** https://github.com/nesbtesh/agentUI/tree/master/apps/cli
- **Binary:** `agentui`
- **License:** MIT
- **Requires:** Node.js 22 or newer
- **Human-readable page:** https://www.agentui.ai/en/agentui-cli/

## Install

```bash
npm install -g @agentuiai/cli
agentui --version
```

Run without installing:

```bash
npx @agentuiai/cli project list
```

## For AI agents: use `--json`

Pass `--json` on the root command and **every** subcommand emits machine-parseable
JSON on stdout. Errors are structured too. This mirrors the AWS CLI and GitHub CLI
approach, and it is the intended way for an agent to drive this tool — do not parse
the human-readable output.

```bash
agentui --json project list
```

```json
{
  "total": 2,
  "count": 2,
  "projects": [
    {
      "id": "cmo8…",
      "appId": "cmo7…",
      "name": "Mercury Dashboard",
      "type": "APP_V2",
      "status": "ACTIVE",
      "published": false,
      "updatedAt": "2026-04-21T14:43:55.867Z"
    },
    { "id": "cmo9…", "appId": "cmo7…", "name": "Nightly Report", "type": "AUTOMATION", "status": "ACTIVE" }
  ]
}
```

`agentui project open --preview --print` prints a URL and nothing else, which is
the CI- and agent-friendly form.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Any error — validation, auth, network, or server. Details on stderr, or on stdout under `--json`. |

## Core concept

A **project** in the CLI is a single **workflow** on the platform (`APP_V2`,
`AUTOMATION`, `TOOL`, or `APP`) — not its enclosing App container. `project sync`
takes a workflow id. The enclosing App is informational only; every CLI operation
scopes to the workflow.

## Quick start

Brand-new app — two commands. `project create` makes the project *and* the local
folder, so no `mkdir` and no separate `project sync`:

```bash
agentui auth login
agentui project create --name "My App"   # → ./my-app with AGENTS.md + skeleton
cd my-app && cat AGENTS.md
```

Where it scaffolds:

| Situation | Scaffolds into |
|---|---|
| current directory is empty | the current directory |
| current directory has files | `./<project-name>` |
| `--dir <path>` passed | exactly `<path>`, created if missing |

Existing project:

```bash
agentui auth login            # emails a 6-digit code
agentui workspace list
agentui workspace select <workspaceId>
agentui project list
agentui project sync <workflowId>
agentui project push --dry-run
agentui project push
```

## The sync → edit → push loop

`sync` writes server-side records to disk as plain files:

```text
.agent.json              # projectId (= workflow id), projectName, projectType,
                         # appId, environment, syncedAt   (gitignored)
.agent-manifest.json     # component ids, versions, workflow ids, codeHash   (gitignored)
.gitignore               # created/updated to hide the two config files
Layout.jsx               # if the workflow has a Layout component
components/              # one .jsx per COMPONENT
pages/                   # one .jsx per PAGE
functions/               # one .jsx per FUNCTION
entities/                # one .schema.json per ENTITY
```

`push` diffs the working tree against the manifest and sends only the difference:

| Local state | Manifest state | Operation |
|---|---|---|
| present, content changed | has entry | `update` |
| present | no entry | `create` |
| missing | has entry | `delete` (opt-in with `--delete`) |

Use `agentui project init <workflowId>` instead of `sync` when the project is
already cloned from git and you only need `.agent.json` and the manifest
bootstrapped without overwriting local files.

## Command reference

### auth

| Command | Does |
|---|---|
| `agentui auth login` | Log in; a 6-digit code is emailed |
| `agentui auth login --email <e> [--code <c>]` | Non-interactive login |
| `agentui auth login --api-key <key>` | Log in with an API key |
| `agentui auth status` | Session state |
| `agentui auth whoami` | Current identity |
| `agentui auth logout` | Clear the session |

### workspace

| Command | Does |
|---|---|
| `agentui workspace list` | Workspaces you belong to |
| `agentui workspace select <workspaceId>` | Set the active workspace |

### project

| Command | Does |
|---|---|
| `agentui project create --name "<name>"` | Create project + scaffold local folder |
| `agentui project list` | Projects (workflows) in the active workspace |
| `agentui project sync <workflowId>` | Pull the workflow to disk |
| `agentui project init <workflowId>` | Bootstrap config only, no overwrite |
| `agentui project status` | Local vs. server state |
| `agentui project diff` | What has changed locally |
| `agentui project push [--dry-run] [--delete]` | Send the difference back |
| `agentui project rename <componentId> <newName>` | Rename a component |
| `agentui project open [--preview] [--print]` | Open the editor or live preview |
| `agentui project link [--scope newTab\|iframe] [--open]` | Mint a pre-authed deep link (7d; `iframe` scope is 1h) |
| `agentui project instructions [--check]` | Are the AI instruction files current? `--check` exits 1 if stale |
| `agentui project settings [set <key> <value>]` | Read/write project settings |

Settings accept `customDomain`, `homePagePath` (by name or file path), and
booleans as `true/false`, `on/off`, `yes/no`, `1/0`. Passing `none`, `null` or an
empty string clears a value.

### env

| Command | Does |
|---|---|
| `agentui env list` / `current` / `status [name]` | Inspect environments |
| `agentui env create <name>` | Create one |
| `agentui env use <name>` | Point the project at one |
| `agentui env promote <from> <to>` | Promote between environments |

### secrets

`agentui secrets list`, `agentui secrets request`. **Secret values never leave the
server** — not in `list`, not in `request` responses, not in a `sync` bundle.

### validate, build, deploy

| Command | Does |
|---|---|
| `agentui validate` | Check for errors before pushing |
| `agentui build [--environment <e>] [--force] [--no-wait]` | Build the bundle |
| `agentui deploy [--dry-run] [--yes]` | Ship a built project |

### functions

`list`, `invoke [id]`, `logs <stepId>`, `stats [stepId]`.

### integrations (consume) and integration (author)

| Command | Does |
|---|---|
| `agentui integrations list [--platform <p>] [--type <t>] [--authenticated\|--not-authenticated]` | Browse integrations |
| `agentui integrations info <id>` | Details |
| `agentui integrations docs <platform>` | Platform docs |
| `agentui integrations alerts` | Integration alerts |
| `agentui integration new [<name>]` | Scaffold one for the community |
| `agentui integration check [file] [--fix]` | Lint it |
| `agentui integration test [file]` | Test it |
| `agentui integration pull <id> [file]` | Pull an existing one |
| `agentui integration publish [file]` | Publish it |
| `agentui integration guide` | Authoring guide |

### skills, packages, blueprints, prompts

| Command | Does |
|---|---|
| `agentui skills …` | Manage skills available to a project |
| `agentui packages list [--category <c>]`, `categories`, `info <name>` | npm packages a project can use |
| `agentui blueprints list`, `info <id>`, `create <id>` | Prebuilt app blueprints |
| `agentui prompts list [--search <q>] [--integration <x>]`, `info <id>` | Prompts a project uses |

### report

`agentui report broken "<description>"` — report something broken or missing
without leaving the terminal.

## Safety and multi-tenant guarantees

- **Path traversal blocked.** `../`, absolute paths, URL-encoded traversal and
  symlinks out of the project directory are rejected on reads, writes and deletes.
- **Multi-tenant isolation.** Every server endpoint verifies the authenticated
  user's `companyId` owns the workflow, step, component and secret being touched.
  Cross-tenant access returns `404`, not `403`, so it does not leak existence.
- **Workflow isolation.** Two workflows inside one App are strictly isolated;
  syncing workflow A never returns workflow B's components.
- **Secret values never leave the server.**
- **Push limits.** Max 50 operations per batch, 1 MB total UTF-8 bytes.
- **Atomic version bumps.** Concurrent pushes each get a unique version — no lost
  updates.
- **Archived projects reject writes** with `404`.

## Related

- What an agent can do with these commands, and what it cannot: https://www.agentui.ai/en/ai-agent-tools/
- AgentUI CLI page: https://www.agentui.ai/en/agentui-cli/
- AgentUI for AI agents (browser assistants): https://www.agentui.ai/en/agents/
- Site index for LLMs: https://www.agentui.ai/llms.txt