Skip to content
ulamsulamsulams docs

CLI reference

Generated from front/cli (ulams schema)

Generated from the CLI’s command registry (ulams schema), so it always matches the binary. Guides: Using the CLI, ulams for AI agents.

Commands

Section titled “Commands”

Global flags

Section titled “Global flags”
Flag Environment Description
--profile <name> ULAMS_PROFILE Profile to use.
--url <origin> ULAMS_URL Instance origin; overrides the profile.
--token-stdin ULAMS_TOKEN Read the token from stdin (there is no –token flag).
--json Shorthand for –output json.
`–output json ndjson yaml
--fields a,b.c Project data (each item of a list) to these paths.
`–input <json @file ->`
--set path=value Set one nested input value (repeatable).
--quiet No stderr progress.
--no-color NO_COLOR Disable colors.
--dry-run Show the plan; make no changes.
--yes ULAMS_YES=1 Confirm destructive commands non-interactively.
`–wait –no-wait, –timeout `
--idempotency-key <key> Sent as Idempotency-Key.
--page, --per-page, --all, --limit <n> Pagination of list commands.
--out <path> Write a binary download to this path (- for stdout).
--debug ULAMS_DEBUG=1 Redacted request log on stderr.
--interactive Allow prompts.

Output envelope (contract 1)

Section titled “Output envelope (contract 1)”

In JSON mode stdout holds exactly one document:

{ "ok": true, "contract": 1, "command": "courses.list", "data": [], "meta": { "page": 1, "perPage": 25, "total": 0, "lastPage": 1, "nextPage": null } }
{ "ok": false, "contract": 1, "command": "courses.get", "error": { "code": "NOT_FOUND", "message": "…", "hint": "…", "status": 404, "retryable": false, "requestId": "…", "details": {} } }

Exit codes

Section titled “Exit codes”
Exit Error code Default hint
1 INTERNAL This is a bug in the ulams CLI. Re-run with –debug and report it.
2 USAGE Run ulams --help or ulams schema to see the available commands.
2 INPUT_INVALID Run ulams describe <command> to see the accepted input.
3 AUTH_REQUIRED Run ulams login --url <origin> or set ULAMS_URL and ULAMS_TOKEN.
3 AUTH_EXPIRED The token was rejected. Run ulams login again.
3 INSECURE_CREDENTIALS Run chmod 600 on the credentials file.
4 FORBIDDEN The user lacks the permission. Run ulams whoami to see roles and token scopes.
4 SCOPE_MISSING The token lacks a scope. Create a token with the required scope.
5 NOT_FOUND Check the id with the matching list command.
6 CONFLICT The resource changed or already exists. Fetch it again and retry.
6 SYNC_CONFLICT Resolve the conflicting elements and retry.
6 IDEMPOTENCY_MISMATCH The idempotency key was reused with a different body. Use a new key.
7 VALIDATION_FAILED The API rejected the input. See error.details.fields.
8 RATE_LIMITED Wait for details.retryAfter seconds and retry.
9 SERVER_ERROR The server failed or is unreachable. Retry later; check the instance health.
9 NETWORK The instance is unreachable. Check the url with ulams whoami and your network.
10 TIMEOUT The operation is still running. Resume it with ulams operations wait <handle>.
11 CONFIRMATION_REQUIRED This command is destructive. Review the plan in error.details.plan and re-run with –yes.
12 FEATURE_DISABLED The feature is not enabled on this instance.
12 UNSUPPORTED_SERVER The server does not support this command. Upgrade the server or the CLI.
13 DIFF_FOUND Differences were found (exit code 13 is expected with –exit-code).