DocsDevelopersCLI

CLI

The rootcx CLI creates projects, scaffolds apps, deploys to your Core, invokes agents, and manages data. It works alongside your AI coding agent of choice.

Installation

curl -fsSL https://rootcx.com/install.sh | sh

Installs to ~/.rootcx/bin/rootcx. Supports macOS (arm64, x86_64), Linux (x86_64, arm64), and Windows (x86_64). The installer adds the binary to your PATH automatically.

On Windows (PowerShell):

irm https://rootcx.com/install.ps1 | iex

Commands

rootcx init

Interactive onboarding. Creates a project, scaffolds your first app, and deploys it.

rootcx init

The CLI asks for an app name, where to run (RootCX Cloud or self-hosted Docker), and credentials. If you chose Cloud, it provisions the workspace (database, networking, DNS, OIDC SSO) in about two minutes.

rootcx new <name>

Scaffold a new app in a new directory. Creates a Vite + React + TypeScript project with the RootCX SDK and a backend worker pre-configured.

rootcx new my_crm

rootcx deploy

Deploy the current project to the connected Core.

rootcx deploy

The deploy pipeline:

  1. Reads manifest.json from the current directory.
  2. Installs dependencies (bun install) if package.json exists.
  3. Builds frontend (bun run build with --base=/apps/{appId}/) if src/ exists.
  4. Installs the manifest to the Core.
  5. Packages and uploads backend/ (if present).
  6. Packages and uploads dist/ (if present).

rootcx status

Check the connection to the Core and display its status.

rootcx status
rootcx status --json

Shows Core URL, reachability, authenticated user, Core version, and current project.

Authentication

rootcx auth login

Sign in to a RootCX Core instance.

rootcx auth login https://myproject.rootcx.com

The CLI detects the Core's auth mode and prompts accordingly:

  • Password login: prompts for email and password.
  • OIDC: opens the browser for SSO.
  • Token: pass --token for non-interactive use (CI pipelines).
rootcx auth login https://myproject.rootcx.com --token eyJ...

Credentials are saved to ~/.rootcx/config.json.

rootcx auth logout

Clear stored credentials.

rootcx auth logout

rootcx auth whoami

Show the currently signed-in user.

rootcx auth whoami
rootcx auth whoami --json

App management

rootcx apps list

List all installed apps on the connected Core.

rootcx apps list
rootcx apps list --json

rootcx apps describe <app_id>

Show app structure (entities, fields, types).

rootcx apps describe my_crm
rootcx apps describe my_crm --json

rootcx apps rm <app_id>

Uninstall an app. Requires confirmation (or pass -y).

rootcx apps rm my_crm
rootcx apps rm my_crm -y

Agents

rootcx agents invoke <app_id> <message>

Invoke an agent and stream the response.

rootcx agents invoke support_bot "What are the open tickets?"
rootcx agents invoke support_bot "And the closed ones?" --session abc123

Streams the agent's response in real-time. Tool calls, approvals, and errors are displayed as they happen.

rootcx agents list

List all deployed agents.

rootcx agents list
rootcx agents list --json

rootcx agents sessions <app_id>

List sessions for an agent.

rootcx agents sessions support_bot
rootcx agents sessions support_bot --json

Data

rootcx data list <app_id> <entity>

List records in an entity.

rootcx data list crm contacts
rootcx data list crm contacts --limit 10 --sort name --order asc

rootcx data query <app_id> <entity> <body>

Query with filters (JSON body).

rootcx data query crm contacts '{"where":{"stage":"lead"},"limit":5}'

rootcx data get <app_id> <entity> <id>

Fetch a single record by ID.

rootcx data get crm contacts 550e8400-...

rootcx data create <app_id> <entity> --body <json>

Create a record.

rootcx data create crm contacts --body '{"first_name":"Alice","email":"alice@example.com"}'

rootcx data update <app_id> <entity> <id> --body <json>

Update a record.

rootcx data update crm contacts 550e8400-... --body '{"first_name":"Alice B."}'

rootcx data delete <app_id> <entity> <id>

Delete a record. Requires confirmation (or pass -y).

rootcx data delete crm contacts 550e8400-...
rootcx data delete crm contacts 550e8400-... -y

Utility

rootcx upgrade

Update the CLI to the latest version.

rootcx upgrade
rootcx upgrade --version 0.15.0

The CLI also checks for updates passively in the background (every 24 hours). Disable with ROOTCX_NO_UPDATE_CHECK=1.

rootcx completions <shell>

Generate shell completions.

# Zsh
rootcx completions zsh > ~/.zfunc/_rootcx

# Bash
eval "$(rootcx completions bash)"

# Fish
rootcx completions fish > ~/.config/fish/completions/rootcx.fish

# PowerShell
rootcx completions powershell >> $PROFILE

Configuration

Config file: ~/.rootcx/config.json

{
  "url": "https://myproject.rootcx.com",
  "token": "eyJ...",
  "refreshToken": "eyJ..."
}

The CLI automatically refreshes expired access tokens using the refresh token. If refresh fails, you are prompted to re-login.

Command aliases

Command Alias
init i
new n
deploy d
status s
apps list apps ls
agents list agents ls
data list data ls
data delete data rm
PreviousREST APINextClaude Code