Deploy and manage an app with the Sureva CLI

Go from an existing team to a running web app with a public URL using sureva CLI v0.1.0. Every step is verified against the CLI source and safe to run verbatim in AI agents and CI pipelines.

Quick path

1. Verify your team — sureva teams list --org <slug>
2. Create the app — sureva apps create --name my-app --type web --region us-east-1 --org <slug>
3. Set environment variables (optional) — sureva env set <app-id> --org <slug> KEY=value
4. Trigger and watch the first deploy — sureva deploys trigger <app-id> --org <slug> --wait
5. Get the public URL — sureva apps get <app-id> --org <slug> | jq -r '.url'
6. Check status and logs as needed

Before you start

• GitHub App installed — installation is web-only at cloud.sureva.com. There is no CLI path.
• Team exists — your org must have at least one team. Teams are created in the web UI only; the CLI can only list them.
• PAT exported — export your personal access token:

  export SUREVA_TOKEN=sapi_<your-token>
  export SUREVA_ORG=<your-org-slug>  # optional; avoids repeating --org

  See Authentication for how to create a PAT.

1. Verify your team

sureva teams list --org <slug>

Extract team slugs with jq:

sureva teams list --org <slug> | jq -r '.[].slug'

If the org has no teams, create one at cloud.sureva.com before continuing. Exit code 4 means a precondition was not met.

2. Create the web app

sureva apps create \
  --name my-app \
  --type web \
  --region us-east-1 \
  --org <slug>

Capture the app ID immediately:

APP_ID=$(sureva apps create \
  --name my-app \
  --type web \
  --region us-east-1 \
  --org <slug> | jq -r '.id')

A successful response looks like this (trimmed for recognition):

{
  "id": "app_01abc...",
  "name": "my-app",
  "type": "web",
  "subdomain": "my-app-a1b2",
  "domain_status": "pending",
  "url": null
}

domain_status is pending and url is absent at creation time. The URL becomes available after the first successful deploy activates the DNS/CDN infrastructure.

When to use —wait on apps create

For web apps, domain_status activates around the first successful deploy. Adding --wait to apps create blocks until the domain is active (timeout 10m). If the domain does not activate within 10m, the command exits 1 with code wait_timeout; if provisioning fails it exits 1 with code domain_failed.

The resilient primary path is to create without --wait and block on deploys trigger --wait instead (step 4), which uses the longer 15m timeout.

3. Configure environment variables (optional)

sureva env set $APP_ID --org <slug> \
  DATABASE_URL=postgres://... \
  REDIS_URL=redis://...

env set performs a full PUT replacement — any key not included in the command is deleted. Verify after setting:

sureva env get $APP_ID --org <slug> | jq 'keys'

4. Trigger and watch the first deploy

sureva deploys trigger $APP_ID --org <slug> --wait

--wait blocks until the deployment reaches a terminal state (timeout 15m). Exit codes:

Exit code	Error code	Meaning
0	—	Deploy succeeded
1	deploy_failed	Deploy reached a failed or cancelled terminal state
1	wait_timeout	Deploy did not complete within 15m

For web apps, --tag is not required. The deploy uses the configured GitHub branch, build command, and output directory.

5. Get the public URL

After step 4 exits 0, the domain is active:

sureva apps get $APP_ID --org <slug> | jq -r '.url'
# https://my-app-a1b2.sureva.com

The default host suffix is sureva.com. The url field is null / absent until domain_status is active.

6. Check status and read logs

# List recent deployments
sureva deploys list $APP_ID --org <slug>

# Get the status of a specific deployment
sureva deploys status $APP_ID <deploy-id> --org <slug>

# Fetch a log snapshot
sureva logs $APP_ID --org <slug>

Get the ID and status of the latest deploy in one command:

sureva deploys list $APP_ID --org <slug> | jq -r '.[0] | "\(.id) \(.status)"'

Delete an app

sureva apps delete $APP_ID --org <slug> --yes

On success, the API returns {"status": "deleting"} and the teardown runs asynchronously. Exit codes:

Exit code	Error code	Meaning
0	—	Teardown dispatched
1	teardown_dispatch_failed	API accepted the request but infrastructure teardown failed to start
4	validation_error	--yes not passed

Use sureva apps get $APP_ID --org <slug> to poll teardown status.

App types beyond web

For api, sse, and web-ssr apps, two extra requirements apply:

• --runtime at create — required: nodejs24, python314, or go126.
• --tag at deploy — deploy a release tag you create externally:

  gh release create v1.0.0 --repo my-org/my-app
  sureva deploys trigger $APP_ID --org <slug> --tag v1.0.0 --wait

Example for an API app:

APP_ID=$(sureva apps create \
  --name my-api \
  --type api \
  --runtime nodejs24 \
  --region us-east-1 \
  --org <slug> | jq -r '.id')

gh release create v1.0.0 --repo my-org/my-api
sureva deploys trigger $APP_ID --org <slug> --tag v1.0.0 --wait

Exit codes and error handling

Key exit codes for this guide’s journey:

Exit code	Error code	Trigger
0	—	Success
1	wait_timeout	apps create --wait or deploys trigger --wait timed out
1	domain_failed	apps create --wait — domain provisioning failed
1	deploy_failed	deploys trigger --wait — deployment failed or was cancelled
1	teardown_dispatch_failed	apps delete — infrastructure teardown failed to start
4	validation_error	Missing --yes, --runtime, --team, or other precondition

See Agent usage for scripting patterns and the full exit code reference.

Related guides

• Deploy a GitHub web landing — first-deploy DNS/CDN lifecycle for web apps.
• CLI Reference — complete flag and exit code reference.
• Authentication — create and manage personal access tokens.