CLI reference

The public entrypoint for CLI commands, arguments, interactive prompts, and doc links.

Stable identifier

appaloft is Appaloft’s official command-line tool. It’s a first-class entrypoint — every command collects user input and executes it through the shared business operations, never bypassing the application layer or maintaining a separate set of business semantics.

Common commands at a glance

appaloft init                                 # Initialize appaloft.yml in the current directory
appaloft up                                   # Deploy the current directory
appaloft login                                # Log in to Appaloft Cloud or a self-hosted instance
appaloft context list                         # View saved local profiles/contexts
appaloft code                                 # Occupy my Sandbox on the default Server
appaloft workspace                            # Manage Workspaces with an embedded native Agent TUI
appaloft dev                                  # Start the local Development TUI / foreground session
appaloft dev . --server <serverId>            # Develop remotely through a live outbound Worker

appaloft project list                         # List projects
appaloft server register --host <host>        # Register a server
appaloft server worker enroll --server <id> --name <name> # Attach an outbound Worker
appaloft resource create --project <id>       # Create a resource

appaloft deployments timeline <deploymentId>  # View the deployment timeline
appaloft resource diagnose <resourceId>       # Generate a safe diagnostic summary
appaloft deployments recovery-readiness <deploymentId>  # Query recovery-readiness status

Every command supports --help for the full argument list; interactive prompts and error recovery suggestions link to this documentation site’s stable pages wherever possible.

Up: first deployment entrypoint

appaloft up [path-or-source] [--yes] [--project <projectId>] [--json]

appaloft up is the primary folder-to-live-app entrypoint. It uses the current directory when the path is omitted, and Git is not required. It reuses the folder’s Project link and folds login into the first Cloud deployment when needed. Coding-agent, CI, and non-TTY runs must pass --yes before login writes, Project creation, or deployment mutation; --json keeps stdout machine-readable while progress stays on stderr. The command exits zero only after terminal success. Terminal failure is non-zero, and a reserved or previous URL is never printed as success.

appaloft deploy remains the supported 1.x compatibility spelling for the exact same workflow. New commands, documentation, and automation should prefer appaloft up. See Your First Deployment for the full task.

Workspace quick entry

appaloft code occupies my Sandbox on the team’s default enrolled Server after login. Source is the remote SHA. Missing Adapter/Profile create the invisible appaloft-remote. The laptop path is not Workspace truth, and dirty files are not uploaded. On a TTY, default code enters the Cloud Agents TUI immediately with the list collapsed and a centered preparing the agent wait, then attaches. Use --no-attach for one-line stderr progress and the session banner without attaching. Default code picks the live session when leftover same-name Profiles exist. --profile is only a fallback pin. --new occupies the cwd origin and does not silently resume whoami. A failed open names the repository and the missing Binding or Profile. Registered BYOS is placement; --server on code or workspace open pins it and managed is not required. Use --local for this-Mac Scratch.

appaloft login
appaloft code
appaloft code --grok
appaloft code --pi
appaloft code --server <serverId>
appaloft code --no-attach
appaloft code --local
appaloft code --profile <installationId>
appaloft workspace open . --profile <workspace-profile> --new --server <serverId>

appaloft workspace open [path|git-remote] accepts the same locators as code and dispatches workspaces.open. A Git worktree still must be clean and pushed; a non-git directory occupies this folder via a git remote and does not resume an unrelated session. See Open an Agent from a local directory for scratch versus durable-open guidance.

appaloft workspace opens the Workspace control TUI on supported interactive macOS/Linux terminals and consumes only existing public operations/read models. Ctrl+] releases Agent focus; f toggles Focus Mode over the same Session; a opens status-valid pause/resume/confirmed terminate actions backed by the same public commands as headless CLI. Use --no-tui, --json, or an explicit subcommand for non-TTY automation and Windows headless use; these paths never load the renderer. See Manage running Workspaces for the full keymap and session boundary.

Development Session quick entry

appaloft dev [path] builds a public Development Plan from deployment configuration and opens the native TUI in an interactive macOS/Linux terminal. Scripts use --no-tui, --detach, or --json; plan/status/logs/stop/reset expose the same replayable lifecycle. A missing renderer produces a clear warning and safely continues in headless foreground mode.

appaloft dev plan .
appaloft dev . --env-file .env.development
appaloft dev status . --json
appaloft dev stop .
appaloft dev reset . --yes

Add --server <serverId> to use a live outbound Server Worker without inbound SSH. See Local Development Sessions for configuration, state, HTTPS, watch, and cleanup behavior.

appaloft login
appaloft login --url https://appaloft.internal.example.com

appaloft login and appaloft auth login connect to Appaloft Cloud (https://app.appaloft.com) by default. First Cloud appaloft up starts that same browser login when no profile exists, then continues — you do not need a separate appaloft login first. appaloft deploy follows the same 1.x compatibility path. To connect to a self-hosted Appaloft instance or another trusted endpoint, pass --url <url> explicitly. After a successful login, the CLI saves the endpoint, profile name, auth reference, and handshake digest to a local CLI profile — this profile lives under APPALOFT_HOME or the user’s local Appaloft home directory, it is not repository config, and it’s never committed to appaloft.yml.

Logging in doesn’t take over deployment, and doesn’t create a Project, Resource, Deployment, Source Link, or domain binding — nor does it stuff control-plane configuration into a deployment request or write a token/cookie into a committed config file.

appaloft auth status
appaloft logout
appaloft context list
appaloft context show
appaloft context use <profile>

The commands above only manage the local profile/context — they never modify any server-side state.

MCP host install

One command leaves default-checked hosts with both the Appaloft skill and Local MCP. Tokens stay in the Appaloft CLI profile, not in editor config:

appaloft login
appaloft setup agent

appaloft setup agent default-checks universal, Claude Code when ~/.claude exists, and Cursor when ~/.cursor exists. It copies byte-identical skills into ~/.agents/skills, ~/.claude/skills, and ~/.cursor/skills, then writes token-free stdio launchers into ~/.claude.json and ~/.cursor/mcp.json. Universal is skills only. OpenCode is listed but not default-checked; pass --agent opencode or appaloft auth mcp opencode install. Explicit siblings remain: appaloft auth mcp cursor install, appaloft auth mcp claude-code install, and appaloft auth mcp opencode install. npx skills add still only copies the skill. Codex still needs the dedicated bearer profile: appaloft auth mcp login then appaloft auth mcp codex install. A directory without git can be deployed with appaloft up.

Non-interactive authentication (AI agents / CI)

Interactive login uses a browser verification-code flow, suited to human operators. When CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CURSOR_AGENT, AIDER_MODEL, or CODEX_CLI is set, or the process is non-TTY / CI=1, appaloft up (and the 1.x compatibility spelling appaloft deploy) and appaloft setup agent print what they would do and do not create a project, deploy, or write skills unless --yes is present. AI agents and CI/automation should not use the browser/verification-code flow as their default authentication path — they should prefer a scoped, expirable token instead:

# A one-off non-interactive command
APPALOFT_TOKEN=<scoped-token> appaloft up --yes

# Read a token from stdin, verify it, and write it to the local profile
appaloft auth token login --stdin

# Read from a controlled secret file (an agent should never open or print this file's contents)
appaloft auth token login --token-file <path>

Never pass a plaintext token as a command-line argument, and never paste a session cookie, bearer token, deploy token, or secret file content into a conversation, log, screenshot, or committed config file.

Remote Appaloft dispatch

With a logged-in profile, or when --control-plane-mode cloud|self-hosted or --control-plane-url <url> is passed explicitly, ordinary business commands first resolve the execution target:

appaloft up --control-plane-mode self-hosted --control-plane-url https://console.example.com

controlPlane.mode: none (the default) keeps using the local CLI/SSH runtime. A remote target performs a compatibility/authentication handshake before the business request, then dispatches the operation through the exact same typed contract as Web/API/SDK — the CLI never maintains a separate business schema.

Without a profile, URL, token, or another trusted remote source, auto and the default behavior fall back to local mode — it never contacts a public Cloud, and never scans the network.

server terminal and resource terminal open a session through the typed API first when targeting a remote; with --attach, the CLI connects directly to the control plane’s WebSocket to forward local terminal input, resize, output, and close frames — it doesn’t initialize local state, and doesn’t read the target server’s SSH credentials.

Some commands (serve, db, remote-state, init, source package commands, and a few others) currently only support local execution; calling them under an explicit remote mode returns control_plane_unsupported rather than silently falling back to local execution. Top-level up / deploy dispatch to a supported remote control plane through the selected profile.

Local documentation links

While a local Appaloft service is running, doc links printed by the CLI preferentially point to local /docs/*, so offline self-hosted users don’t need to reach an external site.

Automation recommendations

When writing automation scripts, prefer explicit flags or config file fields, and avoid depending on interactive input that can’t be replayed (like a confirmation prompt).