CLI

For agents: Use USERLAND_API_KEY from the environment or a saved CLI API key. Install the public CLI as @userland.fun/cli.

Install

npm install -g @userland.fun/cli

Commands

userland login
userland login --no-browser
userland signup
userland auth status
userland auth save-key --api-key "$USERLAND_API_KEY"
userland auth logout
userland auth logout --revoke
userland auth api-keys list
userland auth api-keys create --name "CI deploy key"
userland auth api-keys rename key_... --name "Production deploy"
userland auth api-keys revoke key_... --yes
userland accounts list
userland accounts use "$ACCOUNT_ID"
userland accounts status --account "$ACCOUNT_ID"
userland accounts limits --account "$ACCOUNT_ID"
userland accounts downgrade preview --to starter --account "$ACCOUNT_ID"
userland support open --subject "Deploy failed" --message "The latest release is throwing errors." --app "$APP_ID"
userland apps publish .
userland apps publish . --account "$ACCOUNT_ID"
userland apps list
userland apps list --account "$ACCOUNT_ID"
USERLAND_ACCOUNT_ID="$ACCOUNT_ID" userland apps list
userland apps status "$APP_ID" --account "$ACCOUNT_ID"
userland apps releases "$APP_ID" --account "$ACCOUNT_ID"
userland apps rollback "$APP_ID" "$RELEASE_ID" --account "$ACCOUNT_ID"
userland apps events "$APP_ID" --severity error --limit 25 --account "$ACCOUNT_ID"
userland apps secrets set "$APP_ID" SECRET_NAME --value "$VALUE" --account "$ACCOUNT_ID"
userland apps routes list "$APP_ID" --account "$ACCOUNT_ID"
userland apps slugs list "$APP_ID" --account "$ACCOUNT_ID"
userland apps slugs add "$APP_ID" "$SLUG" --account "$ACCOUNT_ID"
userland apps slugs remove "$APP_ID" "$SLUG" --account "$ACCOUNT_ID"
userland apps domains list "$APP_ID" --account "$ACCOUNT_ID"
userland apps domains add "$APP_ID" "$HOSTNAME" --account "$ACCOUNT_ID"
userland apps domains verify "$APP_ID" "$HOSTNAME" --account "$ACCOUNT_ID"
userland apps domains remove "$APP_ID" "$HOSTNAME" --account "$ACCOUNT_ID"

The launch public CLI source is under userland-public/cli. login starts a browser device-authorization flow, prints a verification URL and user code, waits for browser approval, then saves the approved API key to ~/.userland/credentials.json with 0600 permissions. signup is an alias for the same flow; if the email is new, account creation happens in the browser after email proof.

The CLI does not store platform passwords. App commands use USERLAND_API_KEY first, then the saved API key. auth save-key remains available for CI, support, and manually copied API keys.

auth api-keys list prints metadata only: key id, status, timestamps, prefix, and name. auth api-keys create prints the new raw API key exactly once and does not save it to the credentials file by default. auth api-keys rename updates the key name through PATCH /v0/auth/api-keys/:api_key_id. auth api-keys revoke asks for confirmation unless --yes is passed and treats already-revoked owned keys as a successful no-op.

Account selection

Most users do not need account selection. If no account is selected, app list and app publish use the actor’s default platform account. Team/client workflows can select an account with --account, USERLAND_ACCOUNT_ID, or accounts use.

App commands resolve account selection in this order: --account, USERLAND_ACCOUNT_ID, saved account_id, then the API default account. userland accounts use "$ACCOUNT_ID" writes the saved account id. userland accounts list shows memberships, roles, and which account is default.

Platform account members manage apps, releases, secrets, and app-user invites. App users inside a published app are separate and cannot use CLI/API credentials.

Support

Use userland support open to contact Userland support from an authenticated CLI session:

userland support open --subject "Deploy failed" --message "The latest release is throwing errors." --app "$APP_ID"
cat message.txt | userland support open --subject "Runtime errors" --app "$APP_ID"
userland support open --subject "Billing question" --message "Please check this account." --account "$ACCOUNT_ID"

Support requests include account and plan context, plus app context when --app is supplied. The command prints a correlation_id and the email address Userland will reply to. Use --json for script output.

Status, Limits, And Routes

userland accounts status prints billing access state, grace deadline, active account flags, reasons, and warnings. userland accounts limits prints plan features, manifest limits, deployment limits, runtime limits, release limits, usage limits, current usage, and route counts. userland accounts downgrade preview --to <plan> prints compatibility violations and planned actions before changing entitlements.

userland apps status prints operational state for one app, including whether canonical serving and mutation are currently allowed. Route commands manage slug aliases and custom domains without changing the canonical app-id origin.

Route command output is tab-separated:

<route_id>  <route_type>  <status>  <hostname>  <slug>  <reason>

Errors

Structured API error details are preserved on separate lines:

API 402: Monthly request quota exceeded for the current plan.
error=quota_exceeded
metric=requests.monthly.max
plan_key=free
limit=10000
current=10000
upgrade_required=true

Distribution

The public CLI package is @userland.fun/cli, with source in https://github.com/dwrtz/userland-public/tree/main/cli.

Backward-compatible aliases remain available:

userland publish <dir>
userland releases <app-id>
userland versions <app-id>

Sync Policy

userland-public/cli is the public CLI source of truth during this phase. CLI changes should update the public CLI source, public CLI README, this reference page, command tests, and changelogs together. Validate with:

npm run typecheck
npm run cli:test
npm test