@agentuiai/cli

Command-line tool for the AgentUI platform. Sync projects to your laptop, edit components in your editor, push changes back, manage secrets, run validations — without leaving the terminal.

Built for two audiences:

1. Developers who want a real code-editor workflow (git, VS Code, Cursor) on top of AgentUI projects.
2. AI coding assistants (Claude Code, Codex, Aider) — every command supports --json and returns machine-parseable output, matching the approach of the AWS CLI and GitHub CLI.

0.2.0 breaking change. A "project" is now a workflow, not its enclosing App. project sync takes a workflow id. Existing .agent.json files will need a one-time re-sync. See CHANGELOG.md for the migration.

Table of contents

• Install
• Quick start
• Authentication
• The sync → edit → push workflow
• Command reference
  • auth
  • workspace
  • project
  • secrets
  • validate
  • deploy
  • skills
  • packages
  • blueprints
  • prompts
  • functions
  • integrations
• Global flags
• JSON output mode
• Config files
• Project structure on disk
• Safety and multi-tenant guarantees
• Exit codes
• Troubleshooting

Install

npm install -g @agentuiai/cli

Requires Node 22+. Verify install:

agentui --version

Run without installing:

npx @agentuiai/cli project list

Quick start

# 1. Log in. You'll get an email with a 6-digit verification code.
agentui auth login

# 2. Pick a workspace (your company).
agentui workspace list
agentui workspace select <workspaceId>

# 3. List projects (workflows) in the active workspace.
agentui project list

# 4. Sync a project into the current directory. The id is the "Project ID"
#    column from `project list` — that's the workflow id.
mkdir my-project && cd my-project
agentui project sync <workflowId>

# 4b. (Or, if you cloned the project from git and only need to bootstrap
#     .agent.json + the manifest without overwriting your local files:)
agentui project init <workflowId>

# 5. Open in your editor. Edit existing components, create new ones,
#    delete ones you don't need.
code .

# 6. Preview what will be pushed.
agentui project push --dry-run

# 7. Push. Use --delete to also remove components whose local files were deleted.
agentui project push --delete

Authentication

The CLI uses the same OTP email login as the AgentUI web app.

Log in

agentui auth login

You'll be prompted for your email. AgentUI sends a 6-digit code; paste it to complete the login. The access token is stored at ~/.agentui/credentials.json with 0600 permissions.

Who am I?

agentui auth whoami

  Email:   [email protected]
  Role:    admin
  Company: Acme Inc (cmp_abc123)

Log out

agentui auth logout

Revokes the server session and deletes local credentials.

CI / automated environments

For CI you can't use the interactive OTP flow. Issue a long-lived API key from the AgentUI dashboard and drop it at ~/.agentui/credentials.json:

{ "token": "sk_live_..." , "userId": "usr_...", "email": "[email protected]" }

Or set the AGENTUI_TOKEN environment variable (overrides the file).

The sync → edit → push workflow

A "project" in the CLI is a single workflow on the platform (an APP_V2 SaaS app, an AUTOMATION, a TOOL, or an APP). Its components, pages, functions, entity schemas, and integrations are all server-side records. sync pulls them down as plain files you can edit with any tool; push sends changes back. A workflow's enclosing App container is informational only — it's shown in project status but all CLI operations scope to the workflow.

What sync writes

From the current directory:

.agent.json              # projectId (= workflow id), projectName, projectType,
                         # appId, environment, syncedAt  (gitignored)
.agent-manifest.json     # component ids, versions, workflow ids,
                         # codeHash per component  (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

What push sends

push compares the current working tree against the manifest and sends the difference:

| Local state | Manifest state | Operation | |--------------------------------|----------------|-----------| | File present, content changed | Has entry | update | | File present | No entry | create | | File missing | Has entry | delete (opt-in with --delete) |

Each push is atomic per-operation with a server-side version bump. Concurrent pushes from multiple CLIs never collide on the same version.

What's protected

• Values of secrets are never returned, even to admins, even in JSON mode.
• Database records are never returned by sync — only schemas.
• Integration configs / tokens / auth state are never returned — only the type + whether it's authenticated.

Command reference

auth

| Command | Description | |------------------------------|--------------------------------------------------| | agentui auth login | Interactive email + OTP login | | agentui auth logout | Revoke session and clear credentials | | agentui auth whoami | Show current user, role, and company |

workspace

Alias: ws.

| Command | Description | |----------------------------------|-------------------------------------------------| | agentui workspace list | Show all workspaces you have access to | | agentui workspace select <id> | Switch the active workspace | | agentui workspace current | Print the active workspace |

project

All project commands are scoped to the active workspace. <projectId> is a workflow id — the "Project ID" column from project list.

| Command | Description | |-------------------------------------------|-------------------------------------------------------------| | agentui project create --name "<name>" | Create a blank workflow in the active workspace | | agentui project list | Workflows in the active workspace (paginated) | | agentui project init <workflowId> | Bootstrap manifest for an existing local checkout (no file writes) | | agentui project sync <workflowId> | Pull the workflow into the current directory | | agentui project push | Send local changes back (auto-detects create/update) | | agentui project rename <componentId> <newName> | Rename a component server-side | | agentui project status | Project / workflow / component / entity counts vs last sync | | agentui project diff | Local file changes since last sync |

create flags

• --name <name> — required, project name
• --sync — also sync the new (empty) project into --dir after creating
• --dir <path> — sync target (default: current dir)

Only APP_V2 workflows are created. Legacy APP / AUTOMATION / TOOL types existed in earlier schema versions but the runtime can't execute them end-to-end, so the CLI no longer lets you mint them.

list flags

• --limit <n> — results per page (default 20, max 50)
• --offset <n> — pagination offset
• --all — fetch every page (100 ms throttle between pages)
• --type <t> — filter by workflow type: APP, APP_V2, AUTOMATION, TOOL
• --status <s> — filter by status: ACTIVE, PAUSED, ARCHIVED
• --search <q> — case-insensitive match on workflow name
• --app <appId> — narrow to workflows inside one App container

init flags

• --dir <path> — target directory (default: current dir)
• --environment <env> — environment label to record (default: production)
• --force — overwrite an existing .agent.json / .agent-manifest.json

init is for the case where you've cloned a project from git but .agent.json is gitignored. It hits /cli/projects/:id/sync for metadata only — it never writes any component files. Existing local files become the new baseline (their SHA-256 is recorded in the manifest so the next diff is clean). Files missing locally are surfaced in the summary with a sync hint.

sync flags

• --dir <path> — target directory (default: current dir)
• --incremental — only re-fetch components changed since last sync
• --environment <env> — which AgentUI env to read from (default: production)
• --theirs / --ours / --merge — conflict resolution (mutually exclusive)

sync is 3-way merge aware. Before overwriting any local file, it compares the file's SHA-256 against the codeHash recorded in .agent-manifest.json from the last sync. If a file is locally modified AND the server has a new version (or has deleted/renamed it), sync aborts with an itemized list of conflicts:

Sync aborted: 2 local edit(s) would be overwritten.

Re-run with one of:
  --theirs  overwrite local edits with the server version
  --ours    keep local edits (skip the server version)
  --merge   write server version to <path>.theirs and leave local untouched

Modified locally + new version on server (1):
  ~ components/Button.jsx  (local @ 1.2.0 → server @ 1.3.0)
Modified locally + deleted on server (1):
  - pages/OldPage.jsx

--merge writes a <path>.theirs sidecar file containing the server's version so you can diff and merge by hand. Sidecars are gitignored (*.theirs is added to the managed .gitignore automatically) so server code can't leak into commits.

A TOCTOU recheck runs immediately before each overwrite — if the live file changed during sync (you saved between pre-flight and write), that file is skipped with a warning instead of being silently destroyed. Pass --theirs to force.

push flags

• --dry-run — print the planned operations without sending them
• --delete — include deletions for manifest entries whose local files are gone (off by default for safety; matches git's conservative posture)
• --no-create — skip auto-creating components for new local files
• --no-write-back — don't update .agent-manifest.json with the new component IDs / versions returned by the server (default behaviour writes back)

After a successful push, the local manifest is auto-updated with what the server returned — new component IDs for creates, bumped versions for updates, removed entries for deletes. Without this write-back, a push that creates a brand-new file would leave the new component as "untracked" locally, and the next push would create a duplicate on the server. --no-write-back opts out for tooling that wants the legacy "push doesn't touch local files" contract.

Each operation is reported individually in the output:

  Would push 3 operation(s):

    update  MyButton                        components/MyButton.jsx (2.1KB)
    create  NewThing                        components/NewThing.jsx (1.3KB)
    delete  OldThing                        pages/OldThing.jsx (—)

Naming new files

When you create a new local file, push infers:

• type from the directory: components/ → COMPONENT, pages/ → PAGE, functions/ → FUNCTION, entities/ → ENTITY, Layout.jsx at the root → COMPONENT
• name from the filename (without extension): components/UserCard.jsx → UserCard

To control where a new component lives when the project has multiple workflow steps, read the step IDs from .agent-manifest.json and pass --step <id> (coming soon); today, creates go to the project's first active workflow step.

secrets

Secret names and their descriptions are visible; values are never returned by any CLI command, ever.

| Command | Description | |---------------------------------------------------|----------------------------------------------------------------| | agentui secrets list | Secrets available to the current project | | agentui secrets request <NAME> | Associate an existing secret with the project, or create it |

secrets list flags

• --project <id> — project ID (auto-detected from .agent.json)
• --accessible-only — only show secrets the project's workflows can currently use

secrets request flags

• --description "..." — description for a new secret
• --value <v> — provide the value inline (shows in shell history; prefer --stdin or the interactive prompt)
• --stdin — read the value as a single line from stdin
• --project <id> — project ID

Behavior:

• Scope is this one workflow (the CLI's current project). Sibling workflows inside the same App container are not touched.
• If <NAME> already exists in your company, it's associated with this workflow (if not already). Idempotent — re-running is safe.
• If it doesn't exist and you provide a value, it's created (encrypted via AWS KMS / Azure Key Vault / local AES-256-GCM depending on server config) and associated with this workflow.
• If it doesn't exist and no value is provided, the command returns 404 telling you to pass a value.

Naming rules: UPPER_SNAKE_CASE, must start with a letter, 1–64 chars (e.g. STRIPE_API_KEY). Values are capped at 8 KB.

validate

Runs the platform's canonical codeValidator server-side (same rules the AppCodeGenerator worker enforces). Only code files are scanned — .md, .json, and any non-jsx/js/tsx/ts path is skipped silently. The CLI doesn't keep its own rule copy, so rule coverage always matches what the runtime actually enforces.

agentui validate components/MyComponent.jsx
agentui validate --all                 # validate every component in the manifest
agentui --json validate --all          # machine-parseable findings + skipped count

Findings come back with {severity, file, line, message}. Exit code 1 iff any finding is severity: "error". Run agentui skills info code-validator for the current full rule list — it stays in sync with the backend.

deploy

Runs validation, then pushes to a specific environment.

agentui deploy --env staging
agentui deploy --env production --validate --dry-run

Flags: --env <environment>, --validate (default on), --dry-run.

skills

Platform skill documentation — the same docs the AppCodeGenerator LLM reads.

| Command | Description | |--------------------------------------|-----------------------------------------------------| | agentui skills list | All available skills | | agentui skills info <name> | Full markdown content of a skill | | agentui skills search <query> | Keyword search across skill names and content |

Skill docs are fetched from the server on every invocation — no local cache — so you always see the latest.

packages

Alias: pkg.

| Command | Description | |-----------------------------------------|---------------------------------------------------------------| | agentui packages list | Packages available to components at runtime | | agentui packages list --category <c> | Filter: core, ui, charts, forms, export, etc. | | agentui packages info <name> | Package version and docs (uses the matching skill, if any) | | agentui packages categories | List all categories |

blueprints

Alias: bp.

| Command | Description | |--------------------------------------|----------------------------------------------------------| | agentui blueprints list | Starter templates you can fork from | | agentui blueprints info <id> | Blueprint details | | agentui blueprints create <id> | Create a new project from a blueprint |

prompts

Server-side prompt templates that can be reused in workflows.

| Command | Description | |------------------------------------------|------------------------------------------------| | agentui prompts list | All prompt templates | | agentui prompts list --integration <x> | Filter to an integration | | agentui prompts list --search <q> | Keyword search | | agentui prompts info <id> | Template details |

Entity schemas

Every entity's schema is already written to disk as entities/<name>.schema.json by sync — read them directly from the project folder. There is no agentui entities command (removed — it just duplicated what sync already puts on disk).

functions

Alias: fn.

| Command | Description | |---------------------------------------|-----------------------------------------------------| | agentui functions list | Serverless functions in the project | | agentui functions logs <stepId> | Recent execution logs | | agentui functions stats [stepId] | Invocation count, success rate, latency percentiles |

integrations

Alias: int.

| Command | Description | |-------------------------------------------------|------------------------------------------------------| | agentui integrations list | Workspace integrations | | agentui integrations list --authenticated | Only show connected integrations | | agentui integrations list --not-authenticated | Only show disconnected | | agentui integrations list --platform <p> | Filter by platform (stripe, slack, google, …) | | agentui integrations list --type <t> | Filter by type | | agentui integrations info <id> | Details for one integration | | agentui integrations docs <platform> | Pull integration docs (from skills + prompts) | | agentui integrations alerts | Recent alerts (auth expired, rate-limit, etc.) |

Global flags

Work on every command:

| Flag | Description | |-----------------------|-----------------------------------------------------------------------------| | --json | Output JSON (see JSON output mode) | | --env <environment> | Which AgentUI API to call: development, staging, or production (default) | | --version | Print the CLI version and exit | | --help | Print help for the current command |

JSON output mode

Pass --json on the root command and every subcommand will emit machine-parseable JSON on stdout:

agentui --json project list

{
    "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"
        }
    ]
}

Errors are structured too:

agentui --json project sync does-not-exist

{ "error": "Project not found", "details": null }

On error, the process exits with code 1 — JSON still goes to stdout.

This is the contract AI coding assistants rely on. No ANSI color, no spinners, no tables — just JSON.

Config files

| Path | Contents | |----------------------------------------------|----------------------------------------------------------| | ~/.agentui/credentials.json (0600) | { token, userId, email } | | ~/.agentui/settings.json | { activeWorkspace: { id, name } } | | ./.agent.json (per project) | { projectId, projectName, projectType, appId, environment, syncedAt } — projectId is a workflow id | | ./.agent-manifest.json (per project) | Component map with per-component codeHash, workflow IDs, version snapshots |

Both per-project files are added to .gitignore automatically — don't commit them.

Project structure on disk

After agentui project sync <id>:

my-project/
├── .agent.json
├── .agent-manifest.json
├── .gitignore
├── Layout.jsx
├── components/
│   ├── Header.jsx
│   └── UserCard.jsx
├── pages/
│   ├── Dashboard.jsx
│   └── Settings.jsx
├── entities/
│   └── Patient.schema.json
└── functions/
    └── sendEmail.jsx

• The .agent.json and .agent-manifest.json files are the CLI's state. If you delete them, push won't know how to map your files back to the server.
• File names are sanitized on sync: illegal filesystem characters are stripped, whitespace becomes _, names are capped at 200 chars.
• Duplicate component names inside the same type directory get a _<stepSuffix> disambiguator.

Safety and multi-tenant guarantees

• Path traversal blocked. ../, absolute paths, URL-encoded traversal, and symlinks out of the project directory are all rejected for reads, writes, and deletes.
• Multi-tenant isolation. Every server endpoint verifies the authenticated user's companyId owns the workflow, workflow step, component, and secret being touched. Cross-tenant access returns 404, not 403, to avoid leaking existence. A dedicated test suite (cli.tenant-isolation-smoke.test.js) exercises every /cli/* endpoint from Tenant B against Tenant A's resources with DB-level assertions.
• Workflow isolation. Two workflows inside the same App container are strictly isolated. Syncing workflow A never returns workflow B's components; pushing a workflow-A-scoped op against workflow B's component id fails per-op.
• Secret values never leave the server. Not in secrets list, not in secrets request responses, not in sync bundles.
• Push payload limits. Max 50 operations per batch, 1 MB total UTF-8 bytes (emoji-safe byte counting, not UTF-16 code units).
• Atomic version bumps. Even with N concurrent pushes from different CLIs racing on the same component, each push gets a unique version number — no lost updates.
• Archived projects reject writes. Pushing or requesting secrets on an archived app returns 404.

Exit codes

| Code | Meaning | |------|----------------------------------------------------------| | 0 | Success | | 1 | Any error — validation, auth, network, server error. Inspect stderr or --json stdout for details. |

Troubleshooting

Not authenticated. Run 'agentui auth login' first.' You've never logged in on this machine, or your token was revoked. Run agentui auth login again.

Session expired. Run 'agentui auth login' Your token was valid but the user/session was deleted server-side. Re-login.

No project found. Run 'agentui project sync <id>' first. You're running a project-scoped command outside a synced project directory. Either cd into one or pass --project <id>.

Project not found when you know it exists Three likely causes, in order:

1. You passed an App id instead of a workflow id. <projectId> is a workflow id now (the "Project ID" column of project list).
2. Your .agent.json is from a pre-0.2.0 sync and still holds an App id. Re-sync once with a workflow id to migrate.
3. The authenticated user belongs to a different company than the workflow. Check with agentui auth whoami and agentui workspace current.

Push failed with 1 MB error Your batch is too big. Split into smaller pushes, or drop large components into a separate push.

Components created in the wrong workflow step Today, push creates new components in the project's first active workflow step. For explicit control, pass workflowStepId directly (see the API docs) — a --step flag is planned.

The server returns an error I don't understand Run with --json to get the raw error envelope, or report an issue with the full output: https://github.com/nesbtesh/agentUI/issues.

License

MIT