@exedev/sdk 0.1.0 → 0.3.0

package/dist/commands.gen.d.ts

@@ -1,31 +1,46 @@
-import type { CommandResults } from "./types.js";
-/** Options every command method accepts. */
+import { Transport } from "./client.js";
+import type { ExedevOptions, SSHOptions, SSHResult } from "./client.js";
+import type { CommandResults, RmResponse } from "./types.js";
 export interface CallOptions {
-    /** Aborts the request. */
     signal?: AbortSignal;
 }
-/**
- * The JSON a command returns: the type CommandResults declares for its path,
- * or unknown.
- */
+export interface WaitOptions extends CallOptions {
+    /**
+     * ssh (the default): the VM runs commands. setup: also, its setup script
+     * (exeuntu's exe-setup.service) has finished, and succeeded. Both need ssh permission.
+     */
+    waitUntil?: "ssh" | "setup";
+    /** Deadline in milliseconds, including requests and backoff. Default 60,000; 600,000 for setup. */
+    timeoutMs?: number;
+}
+export interface ReadyOptions extends Omit<WaitOptions, "waitUntil"> {
+    /** Default ssh. Use created to return without probing (and without ssh permission). */
+    waitUntil?: "ssh" | "setup" | "created";
+}
+export interface VMInfo {
+    readonly name: string;
+    readonly tags: readonly string[];
+    readonly sshDest?: string;
+    readonly httpsUrl?: string;
+    readonly status?: string;
+    readonly region?: string;
+    readonly comment?: string;
+    readonly createdAt?: string;
+    /** Why new's --prompt did not reach Shelley, when it did not. Setup scripts report through waitUntil: "setup". */
+    readonly promptError?: string;
+}
 export type CommandResult<P extends string> = P extends keyof CommandResults ? CommandResults[P] : unknown;
-/**
- * How Commands.run writes an option on the command line: bool as --name or
- * --name=false, number and string as --name=value, and repeated as one
- * --name=value per element.
- */
 export type FlagKind = "bool" | "number" | "string" | "repeated";
-/** A positional argument as passed to Commands.run; arrays are spread. */
 export type Arg = string | readonly string[] | undefined;
-/** Options for {@link Commands.ls}. */
+/** Options for {@link ExedevClient.ls}. */
 export interface LsOptions extends CallOptions {
     /** group VMs by none|tag|region|type (default: none) */
-    group?: "none" | "tag" | "region";
+    group?: "none" | "tag" | "region" | "type";
     /** show detailed information */
     l?: boolean;
 }
-/** Options for {@link Commands.new}. */
-export interface NewOptions extends CallOptions {
+/** Options for {@link ExedevClient.new}. */
+export interface NewOptions extends ReadyOptions {
     /** short note about the VM (max 200 bytes) */
     comment?: string;
     /** number of CPUs (default 2; run 'billing plan' for plan limits) */
@@ -61,13 +76,15 @@ export interface NewOptions extends CallOptions {
     /** tag to add to the VM (can be specified multiple times or comma-separated) */
     tag?: string | readonly string[];
 }
-/** Options for {@link Commands.tag}. */
+/** Options for {@link VM.tag}. */
 export interface TagOptions extends CallOptions {
     /** delete tag */
     d?: boolean;
 }
-/** Options for {@link Commands.cp}. */
-export interface CpOptions extends CallOptions {
+/** Options for {@link VM.cp}. */
+export interface CpOptions extends ReadyOptions {
+    /** Name of the copy; omitted to generate one. */
+    name?: string;
     /** copy tags from source VM (use --copy-tags=false to disable) (default: true) */
     "copy-tags"?: boolean;
     /** number of CPUs */
@@ -83,7 +100,7 @@ export interface CpOptions extends CallOptions {
     /** create the copy as a standalone VM with its own reserved capacity (requires a plan with standalone VMs and team approval) */
     standalone?: boolean;
 }
-/** Options for {@link Commands.resize}. */
+/** Options for {@link VM.resize}. */
 export interface ResizeOptions extends CallOptions {
     /** number of CPUs */
     cpu?: number;
@@ -92,22 +109,22 @@ export interface ResizeOptions extends CallOptions {
     /** memory allocation (e.g., 4, 4GB, 8G) */
     memory?: string;
 }
-/** Options for {@link Commands.domainAdd}. */
+/** Options for {@link VM.domainAdd}. */
 export interface DomainAddOptions extends CallOptions {
     /** issue a wildcard (*.<parent>) certificate via DNS-01 delegation */
     wildcard?: boolean;
 }
-/** Options for {@link Commands.domainLs}. */
+/** Options for {@link ExedevClient.domainLs}. */
 export interface DomainLsOptions extends CallOptions {
     /** list domains across all your VMs */
     a?: boolean;
 }
-/** Options for {@link Commands.shareShow}. */
+/** Options for {@link VM.shareShow}. */
 export interface ShareShowOptions extends CallOptions {
     /** show QR code for the URL */
     qr?: boolean;
 }
-/** Options for {@link Commands.shareAdd}. */
+/** Options for {@link VM.shareAdd}. */
 export interface ShareAddOptions extends CallOptions {
     /** message to include in share invitation */
     message?: string;
@@ -116,27 +133,27 @@ export interface ShareAddOptions extends CallOptions {
     /** grant/revoke shell (SSH, Terminal, Shelley) access instead of web-only */
     root?: boolean;
 }
-/** Options for {@link Commands.shareRemove}. */
+/** Options for {@link VM.shareRemove}. */
 export interface ShareRemoveOptions extends CallOptions {
     /** grant/revoke shell (SSH, Terminal, Shelley) access instead of web-only */
     root?: boolean;
 }
-/** Options for {@link Commands.shareAddLink}. */
+/** Options for {@link VM.shareAddLink}. */
 export interface ShareAddLinkOptions extends CallOptions {
     /** show QR code for the URL */
     qr?: boolean;
 }
-/** Options for {@link Commands.shareReceiveEmail}. */
+/** Options for {@link VM.shareReceiveEmail}. */
 export interface ShareReceiveEmailOptions extends CallOptions {
     /** restrict who the VM may email: all|known|owner|none */
     "reply-policy"?: string;
 }
-/** Options for {@link Commands.sshKeyAdd}. */
+/** Options for {@link ExedevClient.sshKeyAdd}. */
 export interface SshKeyAddOptions extends CallOptions {
     /** scope key to VMs with this tag */
     tag?: string;
 }
-/** Options for {@link Commands.sshKeyGenerateApiKey}. */
+/** Options for {@link ExedevClient.sshKeyGenerateApiKey}. */
 export interface SshKeyGenerateApiKeyOptions extends CallOptions {
     /** comma-separated list of allowed commands (empty = defaults) */
     cmds?: string;
@@ -147,12 +164,12 @@ export interface SshKeyGenerateApiKeyOptions extends CallOptions {
     /** scope key to a VM (authenticates to its HTTPS endpoints instead of exe.dev commands) */
     vm?: string;
 }
-/** Options for {@link Commands.integrationsList}. */
+/** Options for {@link ExedevClient.integrationsList}. */
 export interface IntegrationsListOptions extends CallOptions {
     /** include per-VM usage (lastUsedAt, usedByVMs); JSON only */
     usage?: boolean;
 }
-/** Options for {@link Commands.integrationsSetupGithub}. */
+/** Options for {@link ExedevClient.integrationsSetupGithub}. */
 export interface IntegrationsSetupGithubOptions extends CallOptions {
     /** disconnect GitHub account */
     d?: boolean;
@@ -163,7 +180,7 @@ export interface IntegrationsSetupGithubOptions extends CallOptions {
     /** verify GitHub connections are working */
     verify?: boolean;
 }
-/** Options for {@link Commands.integrationsSetupChatgpt}. */
+/** Options for {@link ExedevClient.integrationsSetupChatgpt}. */
 export interface IntegrationsSetupChatgptOptions extends CallOptions {
     /** disconnect ChatGPT account */
     d?: boolean;
@@ -176,7 +193,7 @@ export interface IntegrationsSetupChatgptOptions extends CallOptions {
     /** verify ChatGPT connections are working */
     verify?: boolean;
 }
-/** Options for {@link Commands.integrationsAdd}. */
+/** Options for {@link ExedevClient.integrationsAdd}. */
 export interface IntegrationsAddOptions extends CallOptions {
     /** authenticate as your GitHub user instead of the exe.dev app (github only); pushes and API calls are attributed to your GitHub account */
     "act-as-user"?: boolean;
@@ -213,17 +230,17 @@ export interface IntegrationsAddOptions extends CallOptions {
     /** create as a team integration */
     team?: boolean;
 }
-/** Options for {@link Commands.integrationsRemove}. */
+/** Options for {@link ExedevClient.integrationsRemove}. */
 export interface IntegrationsRemoveOptions extends CallOptions {
     /** operate on a team integration */
     team?: boolean;
 }
-/** Options for {@link Commands.integrationsTest}. */
+/** Options for {@link ExedevClient.integrationsTest}. */
 export interface IntegrationsTestOptions extends CallOptions {
     /** operate on a team integration */
     team?: boolean;
 }
-/** Options for {@link Commands.integrationsEdit}. */
+/** Options for {@link ExedevClient.integrationsEdit}. */
 export interface IntegrationsEditOptions extends CallOptions {
     /** authenticate as your GitHub user instead of the exe.dev app (github only) */
     "act-as-user"?: boolean;
@@ -254,7 +271,7 @@ export interface IntegrationsEditOptions extends CallOptions {
     /** replacement Slack or Discord webhook URL */
     "webhook-url"?: string;
 }
-/** Options for {@link Commands.integrationsAttach}. */
+/** Options for {@link ExedevClient.integrationsAttach}. */
 export interface IntegrationsAttachOptions extends CallOptions {
     /** time-box the attachment to a duration from now (e.g. 2h, 45m); access lapses automatically */
     for?: string;
@@ -263,32 +280,32 @@ export interface IntegrationsAttachOptions extends CallOptions {
     /** time-box the attachment until an RFC3339 instant (e.g. 2026-08-03T20:00:00Z) */
     until?: string;
 }
-/** Options for {@link Commands.integrationsDetach}. */
+/** Options for {@link ExedevClient.integrationsDetach}. */
 export interface IntegrationsDetachOptions extends CallOptions {
     /** operate on a team integration */
     team?: boolean;
 }
-/** Options for {@link Commands.integrationsRename}. */
+/** Options for {@link ExedevClient.integrationsRename}. */
 export interface IntegrationsRenameOptions extends CallOptions {
     /** operate on a team integration */
     team?: boolean;
 }
-/** Options for {@link Commands.teamDisable}. */
+/** Options for {@link ExedevClient.teamDisable}. */
 export interface TeamDisableOptions extends CallOptions {
     /** skip the confirmation prompt (required for non-interactive use, e.g. the web UI) */
     yes?: boolean;
 }
-/** Options for {@link Commands.teamRemove}. */
+/** Options for {@link ExedevClient.teamRemove}. */
 export interface TeamRemoveOptions extends CallOptions {
     /** transfer the member's VMs to this team member before removing them */
     "transfer-vms-to"?: string;
 }
-/** Options for {@link Commands.teamBillingPlan}. */
+/** Options for {@link ExedevClient.teamBillingPlan}. */
 export interface TeamBillingPlanOptions extends CallOptions {
     /** list the plans you can switch to */
     all?: boolean;
 }
-/** Options for {@link Commands.teamBillingUpdate}. */
+/** Options for {@link ExedevClient.teamBillingUpdate}. */
 export interface TeamBillingUpdateOptions extends CallOptions {
     /** billing address city */
     "address-city"?: string;
@@ -315,7 +332,7 @@ export interface TeamBillingUpdateOptions extends CallOptions {
     /** tax ID value shown on invoices */
     "tax-id-value"?: string;
 }
-/** Options for {@link Commands.teamAuthSet}. */
+/** Options for {@link ExedevClient.teamAuthSet}. */
 export interface TeamAuthSetOptions extends CallOptions {
     /** OIDC client ID */
     "client-id"?: string;
@@ -326,21 +343,21 @@ export interface TeamAuthSetOptions extends CallOptions {
     /** OIDC issuer URL (e.g. https://accounts.google.com) */
     "issuer-url"?: string;
 }
-/** Options for {@link Commands.teamSettingsVmPlacementMemberPool}. */
+/** Options for {@link ExedevClient.teamSettingsVmPlacementMemberPool}. */
 export interface TeamSettingsVmPlacementMemberPoolOptions extends CallOptions {
     /** CPUs to reserve for each member pool (required) */
     cpus?: number;
     /** maximum VMs in each member pool (Work defaults to 25 per vCPU, up to 1000) (default: 100) */
     "max-vms"?: number;
 }
-/** Options for {@link Commands.teamVmLs}. */
+/** Options for {@link ExedevClient.teamVmLs}. */
 export interface TeamVmLsOptions extends CallOptions {
     /** group VMs by none|tag|region|type|user|access (default: none) */
-    group?: "none" | "tag" | "region" | "user" | "access";
+    group?: "none" | "tag" | "region" | "type" | "user" | "access";
     /** show detailed information */
     l?: boolean;
 }
-/** Options for {@link Commands.poolNew}. */
+/** Options for {@link ExedevClient.poolNew}. */
 export interface PoolNewOptions extends CallOptions {
     /** number of CPUs reserved for the pool (required; an even number of vCPUs from 2 through 512 (2, 4, 6, and so on; memory is 2 GiB per vCPU)) */
     cpus?: number;
@@ -349,28 +366,28 @@ export interface PoolNewOptions extends CallOptions {
     /** region code for the pool (required unless your team has dedicated hosts, which decide the region) */
     region?: string;
 }
-/** Options for {@link Commands.poolList}. */
+/** Options for {@link ExedevClient.poolList}. */
 export interface PoolListOptions extends CallOptions {
     /** statistics range: live, 24h, 7d, or 30d (requires --usage) (default: live) */
     range?: string;
     /** show live or historical CPU and starvation statistics */
     usage?: boolean;
 }
-/** Options for {@link Commands.poolAdopt}. */
+/** Options for {@link ExedevClient.poolAdopt}. */
 export interface PoolAdoptOptions extends CallOptions {
     /** pool to adopt into (required) */
     pool?: string;
     /** VM to adopt (required) */
     vm?: string;
 }
-/** Options for {@link Commands.poolDetach}. */
+/** Options for {@link ExedevClient.poolDetach}. */
 export interface PoolDetachOptions extends CallOptions {
     /** leave the VM outside any pool instead of making it standalone (only while your team has poolless VMs) */
     poolless?: boolean;
     /** VM to detach from its pool (required) */
     vm?: string;
 }
-/** Options for {@link Commands.poolResize}. */
+/** Options for {@link ExedevClient.poolResize}. */
 export interface PoolResizeOptions extends CallOptions {
     /** new pool size in vCPUs (required unless --max-vms is set; even, from 2 up to the placement limit) */
     cpus?: number;
@@ -379,19 +396,19 @@ export interface PoolResizeOptions extends CallOptions {
     /** maximum VMs in the pool (Work: at most 25 per vCPU, up to 1000) */
     "max-vms"?: string;
 }
-/** Options for {@link Commands.billingPlan}. */
+/** Options for {@link ExedevClient.billingPlan}. */
 export interface BillingPlanOptions extends CallOptions {
     /** list the plans you can switch to */
     all?: boolean;
 }
-/** Options for {@link Commands.billingUsage}. */
+/** Options for {@link ExedevClient.billingUsage}. */
 export interface BillingUsageOptions extends CallOptions {
     /** group usage by: vm */
     group?: string;
     /** time range: cycle (current billing cycle), 24h, 7d, or 30d (default: cycle) */
     range?: string;
 }
-/** Options for {@link Commands.billingCreditsUsage}. */
+/** Options for {@link ExedevClient.billingCreditsUsage}. */
 export interface BillingCreditsUsageOptions extends CallOptions {
     /** break each group down: models under a day or VM, VMs under a model */
     detail?: boolean;
@@ -400,26 +417,26 @@ export interface BillingCreditsUsageOptions extends CallOptions {
     /** calendar month to report, as YYYY-MM (default: this month, UTC) */
     month?: string;
 }
-/** Options for {@link Commands.billingCreditsTransactions}. */
+/** Options for {@link ExedevClient.billingCreditsTransactions}. */
 export interface BillingCreditsTransactionsOptions extends CallOptions {
     /** how many transactions to show, 1-100 (default 20) */
     limit?: string;
 }
-/** Options for {@link Commands.billingCreditsBuy}. */
+/** Options for {@link ExedevClient.billingCreditsBuy}. */
 export interface BillingCreditsBuyOptions extends CallOptions {
     /** retry key so a repeated purchase of the same amount charges once */
     "idempotency-key"?: string;
     /** skip the confirmation prompt (required when not running interactively) */
     yes?: boolean;
 }
-/** Options for {@link Commands.billingCapacity}. */
+/** Options for {@link ExedevClient.billingCapacity}. */
 export interface BillingCapacityOptions extends CallOptions {
     /** Personal capacity in vCPUs: 2, 4, 8, or 16 */
     cpu?: number;
     /** skip interactive confirmation (required for non-interactive changes) */
     yes?: boolean;
 }
-/** Options for {@link Commands.billingUpdate}. */
+/** Options for {@link ExedevClient.billingUpdate}. */
 export interface BillingUpdateOptions extends CallOptions {
     /** billing address city */
     "address-city"?: string;
@@ -446,31 +463,31 @@ export interface BillingUpdateOptions extends CallOptions {
     /** tax ID value shown on invoices */
     "tax-id-value"?: string;
 }
-/** Options for {@link Commands.billingInvoicesList}. */
+/** Options for {@link ExedevClient.billingInvoicesList}. */
 export interface BillingInvoicesListOptions extends CallOptions {
     /** account whose invoices to list: personal or team (default: personal) */
     account?: string;
 }
-/** Options for {@link Commands.billingInvoicesShow}. */
+/** Options for {@link ExedevClient.billingInvoicesShow}. */
 export interface BillingInvoicesShowOptions extends CallOptions {
     /** list VMs without a pool individually */
     vms?: boolean;
 }
-/** Options for {@link Commands.billingReceipts}. */
+/** Options for {@link ExedevClient.billingReceipts}. */
 export interface BillingReceiptsOptions extends CallOptions {
     /** start of the period, YYYY-MM-DD */
     from?: string;
     /** end of the period, YYYY-MM-DD */
     to?: string;
 }
-/** Options for {@link Commands.billingStatement}. */
+/** Options for {@link ExedevClient.billingStatement}. */
 export interface BillingStatementOptions extends CallOptions {
     /** start of the period, YYYY-MM-DD */
     from?: string;
     /** end of the period, YYYY-MM-DD */
     to?: string;
 }
-/** Options for {@link Commands.billingProviderLink}. */
+/** Options for {@link ExedevClient.billingProviderLink}. */
 export interface BillingProviderLinkOptions extends CallOptions {
     /** team size: no marketplace team plans are available */
     size?: string;
@@ -479,22 +496,27 @@ export interface BillingProviderLinkOptions extends CallOptions {
     /** marketplace link token from the exe.dev link page */
     token?: string;
 }
-/** Options for {@link Commands.browser}. */
+/** Options for {@link ExedevClient.browser}. */
 export interface BrowserOptions extends CallOptions {
     /** show QR code for the URL */
     qr?: boolean;
 }
-/** Options for {@link Commands.stat}. */
+/** Options for {@link VM.stat}. */
 export interface StatOptions extends CallOptions {
     /** time range: 24h, 7d, or 30d (default: 24h) */
     range?: string;
 }
-export declare abstract class Commands {
+export declare class ExedevClient {
+    #private;
+    constructor(options: ExedevOptions);
+    /** Reference an existing VM without a request. Use refresh() to fetch its metadata. */
+    vm(name: string): VM;
     /**
-     * Runs the command at path. Undefined args are omitted; options are written
-     * as flags per flags, keyed by flag name.
+     * Delete VMs in one request; the server deletes several at a time. Unlike
+     * vm.rm(), VMs that were missing or could not be deleted do not throw: they
+     * are listed in failed, with reasons in errors. Requires rm permission.
      */
-    protected abstract run(path: string, args: readonly Arg[], options: CallOptions | undefined, flags: Readonly<Record<string, FlagKind>>): Promise<any>;
+    rm(vms: readonly (string | VM)[], options?: CallOptions): Promise<RmResponse>;
     /**
      * Browse documentation
      *
@@ -510,7 +532,7 @@ export declare abstract class Commands {
      *
      * Tag-scoped API keys may run this command.
      */
-    ls(nameOrPattern?: string, options?: LsOptions): Promise<CommandResult<"ls">>;
+    ls(nameOrPattern?: string, options?: LsOptions): Promise<VM[]>;
     /**
      * Create a new VM
      *
@@ -528,225 +550,13 @@ export declare abstract class Commands {
      *
      * Tag-scoped API keys may run this command.
      */
-    new(options?: NewOptions): Promise<CommandResult<"new">>;
-    /**
-     * Delete a VM
-     *
-     * Usage: `rm <vmname>...`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    rm(vmnames: string | readonly string[], options?: CallOptions): Promise<CommandResult<"rm">>;
-    /**
-     * Restart a VM
-     *
-     * Usage: `restart <vmname>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    restart(vmname: string, options?: CallOptions): Promise<CommandResult<"restart">>;
-    /**
-     * Pause a VM (snapshot RAM to disk, free its CPU and memory)
-     *
-     * Usage: `pause <vmname>`
-     *
-     * CLI examples:
-     * ```
-     * pause my-vm     # snapshot RAM to disk; resume later with 'resume my-vm'
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    pause(vmname: string, options?: CallOptions): Promise<CommandResult<"pause">>;
-    /**
-     * Resume a paused VM (restore RAM from disk)
-     *
-     * Usage: `resume <vmname>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    resume(vmname: string, options?: CallOptions): Promise<CommandResult<"resume">>;
-    /**
-     * rename a vm
-     *
-     * Usage: `rename <oldname> <newname>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    rename(oldname: string, newname: string, options?: CallOptions): Promise<CommandResult<"rename">>;
-    /**
-     * Add or remove tags on a VM
-     *
-     * Usage: `tag [-d] <vm> <tag-name> [tag-name...]`
-     *
-     * CLI examples:
-     * ```
-     * tag my-vm prod web        # add tags
-     * tag -d my-vm prod web     # remove tags
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    tag(vm: string, tagNames: string | readonly string[], options?: TagOptions): Promise<CommandResult<"tag">>;
-    /**
-     * Copy an existing VM
-     *
-     * Usage: `cp <source-vm> [new-name] [--pool=<name>] [--memory=<size>] [--cpu=<count>] [--disk=<size>]`
-     *
-     * CLI examples:
-     * ```
-     * cp my-vm                          # copy with auto-generated name
-     * cp my-vm my-vm-copy               # copy with specific name
-     * cp my-vm --cpu=4 --memory=16GB    # copy with different resources
-     * cp my-vm my-pool-copy --pool=build # copy into a team pool
-     * cp my-vm --copy-tags=false        # copy without tags
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    cp(sourceVm: string, newName?: string, options?: CpOptions): Promise<CommandResult<"cp">>;
-    /**
-     * Resize a VM's resources (memory, CPU, disk)
-     *
-     * Usage: `resize <vmname> [--memory=<size>] [--cpu=<count>] [--disk=<size>]`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    resize(vmname: string, options?: ResizeOptions): Promise<CommandResult<"resize">>;
-    /**
-     * Set or clear a short comment on a VM
-     *
-     * Usage: `comment <hostname> <text>`
-     *
-     * CLI examples:
-     * ```
-     * comment my-vm staging copy
-     * comment my-vm "" # clear the comment
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    comment(hostname: string, text: string, options?: CallOptions): Promise<CommandResult<"comment">>;
-    /**
-     * Link a custom domain to a VM
-     *
-     * Usage: `domain add [--wildcard] <vm> <domain>`
-     */
-    domainAdd(vm: string, domain: string, options?: DomainAddOptions): Promise<CommandResult<"domain add">>;
-    /**
-     * Remove a custom domain from a VM
-     *
-     * Usage: `domain rm <vm> <domain>`
-     */
-    domainRm(vm: string, domain: string, options?: CallOptions): Promise<CommandResult<"domain rm">>;
+    new(options?: NewOptions): Promise<VM>;
     /**
      * List custom domains for a VM (or -a for all your VMs)
      *
      * Usage: `domain ls <vm> | domain ls -a`
      */
     domainLs(args?: readonly string[], options?: DomainLsOptions): Promise<CommandResult<"domain ls">>;
-    /**
-     * Show current shares for a VM
-     *
-     * Usage: `share show <vm>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareShow(vm: string, options?: ShareShowOptions): Promise<CommandResult<"share show">>;
-    /**
-     * Set the HTTP proxy port for a VM
-     *
-     * Usage: `share port <vm> [port]`
-     *
-     * CLI examples:
-     * ```
-     * share port mybox 8080
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    sharePort(vm: string, port?: string, options?: CallOptions): Promise<CommandResult<"share port">>;
-    /**
-     * Make the HTTP proxy publicly accessible
-     *
-     * Usage: `share set-public <vm>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareSetPublic(vm: string, options?: CallOptions): Promise<CommandResult<"share set-public">>;
-    /**
-     * Restrict the HTTP proxy to authenticated users
-     *
-     * Usage: `share set-private <vm>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareSetPrivate(vm: string, options?: CallOptions): Promise<CommandResult<"share set-private">>;
-    /**
-     * Share VM with a user via email, or grant shell access with --root
-     *
-     * Usage: `share add <vm> <email|team> [--root] [--message='...']`
-     *
-     * CLI examples:
-     * ```
-     * share add mybox user@example.com
-     * share add mybox user@example.com --message='Check this out'
-     * share add mybox team
-     * share add mybox teammate@example.com --root
-     * share add mybox team --root
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareAdd(vm: string, emailOrTeam: string, options?: ShareAddOptions): Promise<CommandResult<"share add">>;
-    /**
-     * Revoke a user's access to a VM, or downgrade shell access to web with --root
-     *
-     * Usage: `share remove <vm> <email|team> [--root]`
-     *
-     * CLI examples:
-     * ```
-     * share remove mybox user@example.com
-     * share remove mybox team
-     * share remove mybox teammate@example.com --root
-     * share remove mybox team --root
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareRemove(vm: string, emailOrTeam: string, options?: ShareRemoveOptions): Promise<CommandResult<"share remove">>;
-    /**
-     * Create a shareable link for a VM
-     *
-     * Usage: `share add-link <vm>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareAddLink(vm: string, options?: ShareAddLinkOptions): Promise<CommandResult<"share add-link">>;
-    /**
-     * Revoke a shareable link
-     *
-     * Usage: `share remove-link <vm> <token>`
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareRemoveLink(vm: string, token: string, options?: CallOptions): Promise<CommandResult<"share remove-link">>;
-    /**
-     * Enable or disable inbound email for a VM
-     *
-     * Usage: `share receive-email <vm> [on|off] [--reply-policy=all|known|owner|none]`
-     *
-     * CLI examples:
-     * ```
-     * share receive-email mybox on
-     * share receive-email mybox off
-     * share receive-email mybox --reply-policy=known
-     * share receive-email mybox
-     * ```
-     *
-     * Tag-scoped API keys may run this command.
-     */
-    shareReceiveEmail(vm: string, onOrOff?: "on" | "off", options?: ShareReceiveEmailOptions): Promise<CommandResult<"share receive-email">>;
     /**
      * Show user information (email, keys, etc)
      *
@@ -1392,19 +1202,254 @@ export declare abstract class Commands {
      */
     inviteManage(options?: CallOptions): Promise<CommandResult<"invite manage">>;
     /**
-     * Install or upgrade Shelley to the current version
+     * Generate a magic link to log in to the website
      *
-     * Usage: `shelley install <vm>`
+     * Usage: `browser`
+     */
+    browser(options?: BrowserOptions): Promise<CommandResult<"browser">>;
+}
+/** A VM reference. info is a snapshot; refresh() fetches current metadata. */
+export declare class VM {
+    #private;
+    /** @internal Obtain VMs through exe.new(), exe.ls(), exe.vm(), or vm.cp(). */
+    constructor(transport: Transport, info: VMInfo);
+    get info(): Readonly<VMInfo>;
+    get name(): string;
+    get httpsUrl(): string | undefined;
+    get sshDest(): string | undefined;
+    get tags(): readonly string[];
+    /** Run a shell command once. Nonzero exit codes are results, not exceptions. */
+    ssh(command: string, options?: SSHOptions): Promise<SSHResult>;
+    /** Refresh metadata without changing this reference's identity. Requires ls permission. */
+    refresh(options?: CallOptions): Promise<this>;
+    /**
+     * Probe SSH with `true` until it exits successfully. Never reruns a user command.
+     * With waitUntil: "setup", then poll exe-setup.service until the setup script
+     * has finished, throwing VMSetupError (as VMReadyError's cause) if it failed.
+     * Images without that unit (anything but exeuntu) have no setup to wait for.
+     * This does not wait for application servers. Requires ssh permission.
+     */
+    waitUntilReady(options?: WaitOptions): Promise<this>;
+    /**
+     * Delete a VM
+     *
+     * Usage: `rm <vmname>...`
      *
      * Tag-scoped API keys may run this command.
      */
-    shelleyInstall(vm: string, options?: CallOptions): Promise<CommandResult<"shelley install">>;
+    rm(options?: CallOptions): Promise<RmResponse>;
     /**
-     * Generate a magic link to log in to the website
+     * Restart a VM
      *
-     * Usage: `browser`
+     * Usage: `restart <vmname>`
+     *
+     * Tag-scoped API keys may run this command.
      */
-    browser(options?: BrowserOptions): Promise<CommandResult<"browser">>;
+    restart(options?: ReadyOptions): Promise<this>;
+    /**
+     * Pause a VM (snapshot RAM to disk, free its CPU and memory)
+     *
+     * Usage: `pause <vmname>`
+     *
+     * CLI examples:
+     * ```
+     * pause my-vm     # snapshot RAM to disk; resume later with 'resume my-vm'
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    pause(options?: CallOptions): Promise<CommandResult<"pause">>;
+    /**
+     * Resume a paused VM (restore RAM from disk)
+     *
+     * Usage: `resume <vmname>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    resume(options?: ReadyOptions): Promise<this>;
+    /**
+     * rename a vm
+     *
+     * Usage: `rename <oldname> <newname>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    rename(newname: string, options?: CallOptions): Promise<this>;
+    /**
+     * Add or remove tags on a VM
+     *
+     * Usage: `tag [-d] <vm> <tag-name> [tag-name...]`
+     *
+     * CLI examples:
+     * ```
+     * tag my-vm prod web        # add tags
+     * tag -d my-vm prod web     # remove tags
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    tag(tagNames: string | readonly string[], options?: TagOptions): Promise<CommandResult<"tag">>;
+    /**
+     * Copy an existing VM
+     *
+     * Usage: `cp <source-vm> [new-name] [--pool=<name>] [--memory=<size>] [--cpu=<count>] [--disk=<size>]`
+     *
+     * CLI examples:
+     * ```
+     * cp my-vm                          # copy with auto-generated name
+     * cp my-vm my-vm-copy               # copy with specific name
+     * cp my-vm --cpu=4 --memory=16GB    # copy with different resources
+     * cp my-vm my-pool-copy --pool=build # copy into a team pool
+     * cp my-vm --copy-tags=false        # copy without tags
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    cp(options?: CpOptions): Promise<VM>;
+    /**
+     * Resize a VM's resources (memory, CPU, disk)
+     *
+     * Usage: `resize <vmname> [--memory=<size>] [--cpu=<count>] [--disk=<size>]`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    resize(options?: ResizeOptions): Promise<CommandResult<"resize">>;
+    /**
+     * Set or clear a short comment on a VM
+     *
+     * Usage: `comment <hostname> <text>`
+     *
+     * CLI examples:
+     * ```
+     * comment my-vm staging copy
+     * comment my-vm "" # clear the comment
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    comment(text: string, options?: CallOptions): Promise<CommandResult<"comment">>;
+    /**
+     * Link a custom domain to a VM
+     *
+     * Usage: `domain add [--wildcard] <vm> <domain>`
+     */
+    domainAdd(domain: string, options?: DomainAddOptions): Promise<CommandResult<"domain add">>;
+    /**
+     * Remove a custom domain from a VM
+     *
+     * Usage: `domain rm <vm> <domain>`
+     */
+    domainRm(domain: string, options?: CallOptions): Promise<CommandResult<"domain rm">>;
+    /**
+     * Show current shares for a VM
+     *
+     * Usage: `share show <vm>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareShow(options?: ShareShowOptions): Promise<CommandResult<"share show">>;
+    /**
+     * Set the HTTP proxy port for a VM
+     *
+     * Usage: `share port <vm> [port]`
+     *
+     * CLI examples:
+     * ```
+     * share port mybox 8080
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    sharePort(port?: string, options?: CallOptions): Promise<CommandResult<"share port">>;
+    /**
+     * Make the HTTP proxy publicly accessible
+     *
+     * Usage: `share set-public <vm>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareSetPublic(options?: CallOptions): Promise<CommandResult<"share set-public">>;
+    /**
+     * Restrict the HTTP proxy to authenticated users
+     *
+     * Usage: `share set-private <vm>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareSetPrivate(options?: CallOptions): Promise<CommandResult<"share set-private">>;
+    /**
+     * Share VM with a user via email, or grant shell access with --root
+     *
+     * Usage: `share add <vm> <email|team> [--root] [--message='...']`
+     *
+     * CLI examples:
+     * ```
+     * share add mybox user@example.com
+     * share add mybox user@example.com --message='Check this out'
+     * share add mybox team
+     * share add mybox teammate@example.com --root
+     * share add mybox team --root
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareAdd(emailOrTeam: string, options?: ShareAddOptions): Promise<CommandResult<"share add">>;
+    /**
+     * Revoke a user's access to a VM, or downgrade shell access to web with --root
+     *
+     * Usage: `share remove <vm> <email|team> [--root]`
+     *
+     * CLI examples:
+     * ```
+     * share remove mybox user@example.com
+     * share remove mybox team
+     * share remove mybox teammate@example.com --root
+     * share remove mybox team --root
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareRemove(emailOrTeam: string, options?: ShareRemoveOptions): Promise<CommandResult<"share remove">>;
+    /**
+     * Create a shareable link for a VM
+     *
+     * Usage: `share add-link <vm>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareAddLink(options?: ShareAddLinkOptions): Promise<CommandResult<"share add-link">>;
+    /**
+     * Revoke a shareable link
+     *
+     * Usage: `share remove-link <vm> <token>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareRemoveLink(token: string, options?: CallOptions): Promise<CommandResult<"share remove-link">>;
+    /**
+     * Enable or disable inbound email for a VM
+     *
+     * Usage: `share receive-email <vm> [on|off] [--reply-policy=all|known|owner|none]`
+     *
+     * CLI examples:
+     * ```
+     * share receive-email mybox on
+     * share receive-email mybox off
+     * share receive-email mybox --reply-policy=known
+     * share receive-email mybox
+     * ```
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shareReceiveEmail(onOrOff?: "on" | "off", options?: ShareReceiveEmailOptions): Promise<CommandResult<"share receive-email">>;
+    /**
+     * Install or upgrade Shelley to the current version
+     *
+     * Usage: `shelley install <vm>`
+     *
+     * Tag-scoped API keys may run this command.
+     */
+    shelleyInstall(options?: CallOptions): Promise<CommandResult<"shelley install">>;
     /**
      * Allow exe.dev support to log in to a VM
      *
@@ -1412,7 +1457,7 @@ export declare abstract class Commands {
      *
      * Tag-scoped API keys may run this command.
      */
-    grantSupportRoot(vmname: string, onOrOff: "on" | "off", options?: CallOptions): Promise<CommandResult<"grant-support-root">>;
+    grantSupportRoot(onOrOff: "on" | "off", options?: CallOptions): Promise<CommandResult<"grant-support-root">>;
     /**
      * Show vCPU, disk, IO, and network (RX/TX) metrics for a VM
      *
@@ -1427,6 +1472,26 @@ export declare abstract class Commands {
      *
      * Tag-scoped API keys may run this command.
      */
-    stat(vmName: string, options?: StatOptions): Promise<CommandResult<"stat">>;
+    stat(options?: StatOptions): Promise<CommandResult<"stat">>;
+}
+/** Readiness failed after a VM was obtained/created. The VM is not deleted. */
+export declare class VMReadyError extends Error {
+    readonly vm: VM;
+    constructor(vm: VM, cause: unknown);
+}
+/** The VM's setup script failed. details() has the end of its journal. */
+export declare class VMSetupError extends Error {
+    #private;
+    /** systemd's Result for exe-setup.service, e.g. "exit-code", "signal", or "timeout". */
+    readonly result: string;
+    readonly exitCode: number | undefined;
+    readonly signal: number | undefined;
+    constructor(
+    /** systemd's Result for exe-setup.service, e.g. "exit-code", "signal", or "timeout". */
+    result: string, exitCode: number | undefined, signal: number | undefined, output: string);
+    /** The script's last journal lines; may contain secrets. */
+    details(): {
+        output: string;
+    };
 }
 //# sourceMappingURL=commands.gen.d.ts.map