Add `brev launchable create` and `brev launchable deploy` subcommands

[theFong]

Summary

There is no command-line path to create a Brev Launchable or to deploy one into a workspace. Today these flows only exist in the web console (brev.dev/launchable/...). For anything scripted — CI publishing a launchable from a repo, agent harnesses spinning up reproducible demo VMs, automated smoke tests — operators have to either drive the Brev API by hand with curl or build a private wrapper. Both are fragile, both require knowing the org-scoped REST routes, and both reinvent error handling.

This issue asks for two new subcommands under a brev launchable group:

• brev launchable create — POST to /api/organizations/:id/v2/launchables with a payload built from local files (the same shape the wizard sends).
• brev launchable deploy — provision a workspace from an existing launchable id (the same flow https://brev.dev/launchable/deploy/now?launchableID=… triggers when a user clicks it).

Reproduction (today)

$ brev launchable --help
Error: unknown command "launchable" for "brev"

$ brev start "https://brev.dev/launchable/deploy/now?launchableID=env-..."
panic: invalid launchable URL: …

goroutine 1 [running]:
github.com/brevdev/brev-cli/pkg/cmd/start.MakeNewWorkspaceFromURL({0x16b48321b, 0x53})
    /go/src/github.com/brevdev/brev-cli/pkg/cmd/start/start.go:561 +0x4cc
github.com/brevdev/brev-cli/pkg/cmd/start.maybeStartFromGitURL(0x14000225c80, …)
    /go/src/github.com/brevdev/brev-cli/pkg/cmd/start/start.go:217 +0x7c
…

brev start does have machinery for launchable URLs (the binary's string table contains Deploying launchable: %q, failed to fetch launchable %q: %w, invalid launchable URL: %w, /launchable/deploy/now?launchableID=), but the call path panics on any URL the user supplies in this form.

Working around it currently requires either the web console or hand-crafted API calls. Examples of routes I had to discover by reading strings output on the binary:

• POST /api/organizations/:org/v2/launchables (create — works)
• POST /api/organizations/:org/v2/launchables/edit (works, with id, drop viewAccess)
• POST /api/organizations/:org/workspaces (returns BadRequestError: Legacy workspace version unsupported)
• POST /api/users/me/workspaces, /api/launchables/:id/deploy, /api/launchables/:id/launch, /api/v2/workspaces, etc. — all 404

Whatever the web frontend at brev.dev/launchable/deploy/now calls to actually provision a VM is not surfaced anywhere a CLI user can find it.

What we'd like

brev launchable create

Read a payload from a path (or stdin) and POST it to /api/organizations/:org/v2/launchables. On success, print the new launchable's id and shareable URL.

# From a single JSON file containing { name, description, viewAccess,
# createWorkspaceRequest, buildRequest, file? }
brev launchable create --from ./launchable.json

# Or with the lifecycle script broken out (mirrors how the web wizard
# splits them) — the CLI inlines the script into vmBuild.lifeCycleScriptAttr.script.
brev launchable create \
  --name "dex-ui" \
  --description "Browser control plane for OpenShell" \
  --view-access public \
  --instance-type n1-standard-2 \
  --workspace-group GCP \
  --region us-west1 \
  --sub-location us-west1-a \
  --storage 256 \
  --image-id "projects/ubuntu-os-cloud/global/images/family/ubuntu-2404-lts-amd64" \
  --port 3000:dex-ui:secure-link \
  --setup-script ./launchable-setup.sh

Output:

launchable id: env-3Dvdn5kvH5MJ28hKWdtU2GbkC4W
share url:     https://brev.dev/launchable/deploy/now?launchableID=env-3Dvdn5kvH5MJ28hKWdtU2GbkC4W

brev launchable edit and brev launchable list are obvious follow-ups; this issue scopes the MVP to create since that's the entry point.

brev launchable deploy

Provision a new workspace from an existing launchable id. Same flow as clicking the share URL. Should reject any combination that mixes the launchable's create-workspace defaults with conflicting flags rather than silently overriding.

# Default — pull every field from the launchable's createWorkspaceRequest
brev launchable deploy env-3Dvdn5kvH5MJ28hKWdtU2GbkC4W

# With a name + detached so a script can poll separately
brev launchable deploy env-3Dvdn5kvH5MJ28hKWdtU2GbkC4W \
  --name dex-ui-smoketest \
  --detached

Output (detached):

workspace id:   <id>
workspace name: dex-ui-smoketest
state:          DEPLOYING
poll with:      brev ls dex-ui-smoketest

Output (foreground):

[deploy] provisioning n1-standard-2 in us-west1-a…
[deploy] reached BUILDING after 38s
[deploy] reached RUNNING after 2m41s
[deploy] lifecycle script in progress (poll /var/log/brev/oncreate-lifecycle-script-*.log for details)
[deploy] workspace healthy after 6m12s
secure link: https://3000-…brev-prod.ngc.nvidia.com/

Non-goals for this issue

• Listing org launchables and showing per-launchable launch counts. Trackable separately as brev launchable list / brev launchable show.
• Authoring launchables with a fully-interactive TUI. The MVP is non-interactive + scriptable.

Why this matters

We just published a Launchable for dex-ui by:

1. Hand-crafting the JSON payload from API-shape notes (api-shapes.md).
2. Extracting the operator's Brev access token from ~/.brev/credentials.json and POSTing the create request via curl.
3. Iterating with POST .../v2/launchables/edit to fix storage units, missing imageId, etc.
4. Asking the user to click the share URL because we couldn't programmatically launch.

Steps 1–3 should be one command. Step 4 should be the second. Without these, every agent or CI flow that wants to publish + smoke-test a Launchable has to keep reinventing the wheel.

[theFong]

Cross-link: there's an open PR for the create half of this — #357 (Launchable Create Cli) by @tylerfong on branch launchable-create-cli. Worth picking up / dusting off if it's still relevant.

Once brev launchable create lands, the brev launchable deploy half of this issue becomes the remaining gap.

[cjagwani]

Cross-linking the focused NemoClaw pre-tag qualification design: NVIDIA/NemoClaw#6943

The deploy half of this issue has moved forward: current Brev CLI supports brev create --launchable <id-or-url>, and a read-only dry run against the public NemoClaw Launchable succeeds. For unattended release qualification, the remaining contract is broader than “can deploy an existing Launchable.”

Could a Brev owner confirm that this issue is the umbrella—or link the delivery tickets and owners—for these guarantees?

1. Exact image preservation: a Launchable can store an immutable GCP image self-link, or a family is resolved exactly once and pinned before workspace creation. The same reference must survive Launchable storage and deployment.
2. Versioned machine-readable receipt: create/revise/deploy returns JSON containing Launchable ID, immutable revision/version, workspace ID, and correlation/idempotency identity.
3. Boot-source provenance: readback returns the source image name, numeric GCP image ID, and immutable self-link actually used to boot. A created-disk self-link is not sufficient.
4. Supported CI authentication: the API-key flow is explicitly supported for unattended CI, with defined org/role scope, expiry, rotation, revocation, and secret-handling policy.
5. Structured readiness: documented provisioning/build/shell/health states, terminal success/failure semantics, and polling behavior.
6. Verified cleanup: delete by workspace ID, idempotent already-absent behavior, a terminal absence check, and a TTL/janitor fallback.

The qualification lane will compare all three boot-source fields with an immutable image manifest before running E2E. Family-only success without immutable readback is intentionally non-green.

This request does not ask Brev to own NemoClaw’s image build, browser onboarding, runtime assertions, or release verdict. Those remain in brevdev/nemoclaw-image and NVIDIA/NemoClaw.

[cjagwani]

Follow-up: the transport-neutral NemoClaw receipt and cleanup schema has been reviewed and is recorded in #6943. A no-cloud prototype validator was intentionally removed from NVIDIA/NemoClaw#7043 because there is no supported Brev adapter to consume it yet; implementation will happen with the real authoritative response path rather than as an unused compatibility layer.

That contract review makes two details of the Brev-owner interface explicit:

• Launchable ID/revision and workspace ID must come from separately persisted authoritative operation results; a normalized receipt cannot self-attest them. Workspace readback must also identify the Launchable ID/revision actually used.
• The browser gate additionally needs a supported machine-readable public secure-link base URL for the created workspace/Launchable port, plus a stable hostname/origin policy. NemoClaw must be able to validate HTTPS and expected Brev ownership before entering an inference credential, and must reject cross-origin redirects. SSH port forwarding is useful diagnostically but would bypass the customer-facing Launchable ingress and cannot qualify this path.

Could the eventual JSON create/deploy/readiness response include that secure-link URL (or a supported structured lookup for it) along with the six guarantees above? No live workspace is being requested while this interface remains unaccepted.

[cjagwani]

@theFong Since you opened this umbrella issue, could you confirm the appropriate Brev owner or delivery ticket for the remaining CI contract in the two comments above?

We understand that a canonical GCP family path resolves natively to the latest non-deprecated image. The remaining blocker is not family lookup itself: unattended qualification needs authoritative create/deploy IDs, immutable Launchable revision, resolved and actually booted image readback, structured readiness, supported CI authentication, verified deletion/absence, and a machine-readable secure-link URL/origin contract. No private API or live resource is being requested while that path is unaccepted.

[cjagwani]

Scope update after the accepted #6943 Phase 4 design and the current #7043 implementation:

For this qualification slice, new brev launchable create/deploy subcommands are no longer blocking. Brev CLI #347 added brev create <name> --launchable <env-id> --detached; it is present in v0.6.330, and #7043 pins that release and checksum.

The workflow does not create, edit, or repoint a Launchable. It deploys one standing Launchable backed by the staging image family, waits on brev ls --json, verifies the actual GCP boot disk's immutable sourceImage and sourceImageId against the accepted manifest, runs E2E, then calls brev delete and verifies repeated absence.

Therefore Launchable creation/editing, immutable Launchable revisions and receipts, pre-provision image pinning, browser secure-link qualification, immutable-ID deletion, and TTL/janitor guarantees are deferred for this slice.

The remaining Brev-owner confirmations are:

1. brev login --api-key --org-id is supported for unattended CI, including intended org/role scope and rotation/revocation expectations. The intended key must support Launchable GET, workspace list/create/delete, /api/me/keys, brev exec, and brev copy; a successful local login only proves the key was saved.
2. The v0.6.330 interfaces used by the lane—brev create --launchable, the brev ls --json workspace/readiness fields, and brev delete—are supported automation contracts with stable terminal-state meanings.
3. An owner accepts lifecycle, quota/cost, and leaked-workspace cleanup responsibility for the standing staging Launchable.

Could a Brev owner confirm those points or link the appropriate owners/tickets? The broader Launchable-create and richer receipt work can remain tracked separately.

[cjagwani]

Small correction to the final focused lane in NVIDIA/NemoClaw#7270: it does not use brev copy. The exact Brev surface requiring owner confirmation is brev login --api-key --org-id, brev ls --json, brev create --launchable --detached, brev exec --host, and brev delete, including stable readiness fields and unattended CI support. The enable flag remains absent until that confirmation.

[cjagwani]

Post-merge focused owner request for NVIDIA/NemoClaw#7270:

The staging Launchable lane is now merged but intentionally disabled. A read-only dry run against the configured Launchable ID confirms Nemoclaw CI/CD Launchable and the expected family projects/brevdevprod/global/images/family/nemoclaw-brev-staging-cpu; no workspace was created. The pinned v0.6.330 archive checksum and tagged source also confirm the exact command paths exist.

Could a Brev owner confirm only these remaining points for this focused lane?

1. brev login --api-key --org-id is supported for unattended CI with the intended org scope and rotation/revocation expectations.
2. The v0.6.330 surfaces brev ls --json, brev create --launchable --detached, brev exec --host, and brev delete are supported automation contracts, including the readiness fields and terminal meanings used by the lane.
3. A named owner accepts quota/cost and leaked-workspace cleanup responsibility for this standing staging Launchable.

The lane does not create, edit, repoint, or pin a Launchable and does not require the broader receipt/browser contracts previously discussed. Its enable variable remains absent pending this confirmation and producer WIF readiness.