CLI Reference

Complete reference for the sureva CLI. All commands output JSON by default. Use --output table for human-readable terminal output.

Global flags

Flag	Values	Default	Description
--output	json|table	json	Output format
--org <slug>	string	—	Organization slug; overrides SUREVA_ORG and config file
--config <path>	path	—	Alternate config file path
--json	—	—	Only valid with --help; emits machine-readable command tree JSON

Commands

version

sureva version
# or
sureva --version

Returns version information as JSON:

{ "version": "0.x.y", "commit": "...", "built_at": "..." }

---

auth whoami

sureva auth whoami

Shows the user identity (email / user ID) for the current token.

---

auth token create

sureva auth token create [--name <string>] --expires-at <RFC3339>

Creates a personal access token. The raw token value (sapi_<hex>) is shown exactly once and cannot be retrieved again.

Flag	Required	Description
--name	No	Human-readable label for the token; defaults to cli-token if omitted
--expires-at	Yes	Expiry in RFC 3339 format, e.g. 2026-12-31T00:00:00Z

---

auth token list

sureva auth token list

Lists all personal access tokens for the authenticated user. The raw token value is never shown in list output.

---

auth token revoke

sureva auth token revoke <id>

Revokes the token with the given ID.

---

auth login — not implemented

sureva auth login is a stub that always returns a not_implemented error. Device-flow authentication is planned for a future release. Create tokens via auth token create or via the Sureva web app instead.

---

orgs list

sureva orgs list

Lists all organizations the authenticated user belongs to.

---

teams list

sureva teams list --org <slug>

Lists all teams in the resolved organization.

Flag	Required	Description
--org	Yes	Organization slug

Teams are created in the web UI

sureva teams list can only LIST teams. Creating a team requires the Sureva web app at cloud.sureva.com — there is no CLI path for team creation.

---

apps list

sureva apps list [--org <slug>]

Lists apps. Without --org, returns a flat cross-organization list. With --org, scopes results to that organization.

Flag	Required	Description
--org	No	Organization slug

Each app includes a composed url field (https://{subdomain}.sureva.com) when domain_status is active. The url field is absent until the domain is active (typically after the first successful deploy).

---

apps get

sureva apps get <app-id> --org <slug>

Returns full details for a single app.

Flag	Required	Description
--org	Yes	Organization slug

The response includes a composed url field (https://{subdomain}.sureva.com). The url field is absent (omitempty) until domain_status reaches active. Default host suffix is sureva.com; override with SUREVA_DOMAIN_SUFFIX or the domain_suffix config key.

---

apps create

sureva apps create --name <string> --type <type> --region <region> --org <slug> [options]

Creates a new application.

Flag	Required	Description
--name	Yes	Application name / slug
--type	Yes	web | web-ssr | api | sse
--region	Yes	us-east-1 | us-east-2 | sa-east-1
--runtime	Required when --type is not web	nodejs24 | python314 | go126
--team	No	Team slug or ID (auto-selects when org has exactly one team)
--wait	No	Wait for domain to become active before returning
--wait-interval	No	Polling interval (default 5s)
--wait-timeout	No	Maximum wait time (default 10m)

Exit codes for apps create

Precondition failures (exit code 4): missing --runtime for non-web types; org has no teams; org has multiple teams and --team is not specified; --team value not found.

--wait failures (exit code 1): wait_timeout — domain did not activate within --wait-timeout (default 10m); domain_failed — domain provisioning reached a failed terminal state.

Note: the --wait-timeout for apps create is 10m, which is different from deploys trigger’s 15m timeout.

---

apps delete

sureva apps delete <app-id> --org <slug> --yes

Initiates async teardown of an application.

Flag	Required	Description
--org	Yes	Organization slug
--yes	Yes	Confirm deletion (required to prevent accidental deletion in scripts)

Exit codes for apps delete

Exit code 4: --yes not passed — required to confirm deletion.

Exit code 1: teardown_dispatch_failed — the API accepted the request but infrastructure teardown failed to start. The app is marked for deletion; retry or check the API for status.

Teardown is asynchronous and may take several minutes. The command returns immediately after the API accepts the request with {"status": "deleting"}.

---

env get

sureva env get <app-id> --org <slug> [--reveal]

Reads app environment variables. Values are masked (***) by default.

Flag	Required	Description
--org	Yes	Organization slug
--reveal	No	Show unmasked values

---

env set

sureva env set <app-id> --org <slug> KEY=VALUE [KEY=VALUE...]

Replaces all environment variables for the app (full PUT replacement). Any key not included in the command is deleted.

Flag	Required	Description
--org	Yes	Organization slug

---

deploys trigger

sureva deploys trigger <app-id> --org <slug> [--tag <release-tag>] [--env-id <id>] [--wait]

Triggers a new deployment.

Flag	Required	Description
--org	Yes	Organization slug
--tag	Required for API and SSE app types; optional for web apps	Release tag to deploy
--env-id	No	Target environment ID (defaults to the app’s default environment)
--wait	No	Wait for deployment to reach a terminal state before returning
--wait-interval	No	Polling interval (default 5s)
--wait-timeout	No	Maximum wait time (default 15m)

—tag requirement and —wait exit codes

--tag is required for API and SSE app types. Web apps can trigger a deploy without --tag. Omitting --tag for an API or SSE app returns a validation error (Exit code 4).

--wait failures (exit code 1): deploy_failed — deployment reached a failed or cancelled terminal state; wait_timeout — deployment did not complete within --wait-timeout.

Note: the --wait-timeout for deploys trigger is 15m, which is longer than apps create’s 10m timeout.

---

deploys list

sureva deploys list <app-id> --org <slug>

Lists recent deployments for the app.

Flag	Required	Description
--org	Yes	Organization slug

---

deploys status

sureva deploys status <app-id> <deploy-id> --org <slug>

Returns the status and details of a single deployment.

Flag	Required	Description
--org	Yes	Organization slug

---

logs

sureva logs <app-id> --org <slug> [--env-id <id>]

Fetches a non-streaming log snapshot. Automatically resolves the default environment when --env-id is omitted.

Flag	Required	Description
--org	Yes	Organization slug
--env-id	No	Environment ID (defaults to app’s default environment)

---

Exit codes

Exit code	Meaning
0	Success
1	General error / API error
2	Auth error (401 / 403 / missing token)
3	Not found (404)
4	Validation / bad input (400 / 422)
5	Network error

Use exit codes in scripts and agents to handle failures without parsing error text. See Agent usage for scripting patterns.