@easybits.cloud/cli 0.6.1 → 0.8.0

package/README.md

@@ -36,7 +36,7 @@ another server (default `https://www.easybits.cloud`; `baseUrl` in `~/.easybitsr
 # Sandboxes (alias: sb)
 easybits sandboxes ls
 easybits sandboxes create --template node --name scratch --dotenv .env
-easybits sandboxes create --size m --timeout 1800 --no-wait   # size s|m|l|xl (plan-gated)
+easybits sandboxes create --size m --ttl 1800 --no-wait   # size s|m|l|xl (plan-gated)
 easybits sandboxes get sb_abc123
 easybits sandboxes exec sb_abc123 -- npm test
 easybits sandboxes logs sb_abc123 --unit myapp --lines 100 --since "10 min ago" --grep ERROR
@@ -50,7 +50,7 @@ easybits sandboxes destroy sb_abc123 --yes
 
 # Hosting: permanent machines (alias: deploy)
 easybits machines ls
-easybits machines deploy sb_abc123 -m "v1.2"
+easybits deploy sb_abc123 -m "v1.2"   # = machines deploy
 easybits machines releases sb_abc123 --limit 5
 easybits machines logs sb_abc123 --lines 100 --grep ERROR
 easybits machines rollback sb_abc123 rel_789
@@ -75,31 +75,37 @@ easybits db rm leads --yes
 # Agents
 easybits agents ls
 easybits agents create --template goose --name helper --dotenv .env
-easybits agents message ag_123 "hello"
-easybits agents message ag_123 "and now?" --session ses_456   # continue a conversation
-easybits agents destroy ag_123 --yes
+easybits agents get helper          # by name or id
+easybits agents message helper "hello"
+easybits agents message helper "and now?" --session ses_456   # continue a conversation
+easybits agents destroy helper --yes
 
 # Files, websites, account
 easybits files ls
 easybits files upload ./report.pdf
-easybits files delete FILE_ID --yes
+easybits files rm FILE_ID --yes
 easybits websites ls
 easybits providers                   # storage provider (Tigris by default)
 easybits usage
 
 # MCP, SSH, docs
-easybits config        # MCP config (streamable HTTP)
-easybits mcp           # MCP config (stdio)
+easybits whoami        # account and where the credential comes from
+easybits mcp config    # MCP config (streamable HTTP)
+easybits mcp config --stdio   # MCP config (stdio)
 easybits ssh-key       # public key for sandbox SSH
 easybits docs cli      # a docs section as markdown (--en for English)
 easybits docs --open   # open the docs in your browser
 ```
 
+**Names or ids.** Wherever a command takes an agent, a sandbox/machine or a database, you can
+pass its name instead of the id (`easybits sb exec scratch -- ls`, `easybits domains ls shop`).
+The match is exact and case-insensitive; if two share the name the CLI exits 2 and lists the ids.
+
 Every command has help with examples: `easybits <command> <subcommand> --help`
 (or `easybits help <command> <subcommand>`). A typo gets a "Did you mean" suggestion.
 
 **Destructive commands** (`db rm`, `agents destroy`, `sandboxes destroy`, `domains rm`,
-`files delete`) ask before acting in a terminal: `[y/N]`, or typing the name/id for
+`files rm`) ask before acting in a terminal: `[y/N]`, or typing the name/id for
 irreversible ones (a database, an agent, a permanent sandbox). Without a terminal they
 never prompt — and neither do they with `--json`: pass `--yes` / `-y`, or they exit `2`.
 
@@ -129,6 +135,21 @@ Host *.ghosty
 
 Full reference: https://www.easybits.cloud/docs#cli · https://www.easybits.cloud/en/docs/cli.md
 
+## Changes in 0.8.0
+
+- One naming rule (like `gh`): `easybits <noun> <verb>`. Old spellings still work and print the new
+  one on stderr (never with `--json`):
+  `easybits config` → `easybits mcp config`; `easybits mcp` → `easybits mcp config --stdio`;
+  `easybits deploy <machine>` is now the verb (= `machines deploy`), so `deploy ls` → `machines ls`;
+  `machines release` → `machines deploy` (it clashed with `releases`);
+  `sandboxes create --timeout` → `--ttl` (`--timeout` stays in `exec`, where it caps the command).
+- `files rm` is the name (`delete` still works), like `db rm` and `domains rm`.
+- New `easybits whoami`: account email and where the credential comes from.
+
+## Changes in 0.7.0
+
+- Agents, sandboxes/machines and databases by **name** anywhere an id goes; `easybits agents get`.
+
 ## Changes in 0.6.1
 
 - Help: `--yes` is no longer listed as a global flag; it lives on each destructive command

package/dist/index.js

@@ -495,7 +495,8 @@ var providers = {
   synopsis: "providers",
   leaf: {
     summary: "Show storage providers",
-    usage: "easybits providers [list]",
+    usage: "easybits providers",
+    examples: ["easybits providers", "easybits providers --json"],
     async run(ctx) {
       const data = {
         defaultProvider: "tigris",
@@ -508,60 +509,57 @@ var providers = {
     }
   }
 };
-var config = {
-  name: "config",
+var mcp = {
+  name: "mcp",
   group: "MCP",
-  summary: "Print MCP config JSON (streamable HTTP)",
-  synopsis: "config",
-  leaf: {
-    summary: "Print MCP config JSON (streamable HTTP) with your key",
-    usage: "easybits config",
-    examples: ["easybits config > .mcp.json"],
-    async run(ctx) {
-      const apiKey = resolveApiKey(ctx);
-      const baseUrl = await resolveBaseUrl3();
-      console.log(
-        JSON.stringify(
-          {
+  summary: "Print the MCP config JSON for your agent or editor",
+  synopsis: "mcp",
+  subs: {
+    config: {
+      summary: "Print MCP config JSON: streamable HTTP with your key, or stdio (npx @easybits.cloud/mcp)",
+      usage: "easybits mcp config [--stdio]",
+      options: { stdio: { type: "boolean", description: "stdio config (npx @easybits.cloud/mcp) instead of streamable HTTP" } },
+      examples: ["easybits mcp config > .mcp.json", "easybits mcp config --stdio"],
+      async run(ctx) {
+        if (bool(ctx, "stdio")) {
+          const config2 = {
             mcpServers: {
-              easybits: {
-                type: "streamable-http",
-                url: `${baseUrl}/api/mcp`,
-                headers: { Authorization: `Bearer ${apiKey || "eb_sk_live_YOUR_KEY"}` }
-              }
+              easybits: { command: "npx", args: ["-y", "@easybits.cloud/mcp"], env: { EASYBITS_API_KEY: "eb_sk_live_YOUR_KEY" } }
             }
-          },
-          null,
-          2
-        )
-      );
+          };
+          console.log(JSON.stringify(config2, null, 2));
+          return;
+        }
+        const apiKey = resolveApiKey(ctx);
+        const baseUrl = await resolveBaseUrl3();
+        const config = {
+          mcpServers: {
+            easybits: {
+              type: "streamable-http",
+              url: `${baseUrl}/api/mcp`,
+              headers: { Authorization: `Bearer ${apiKey || "eb_sk_live_YOUR_KEY"}` }
+            }
+          }
+        };
+        console.log(JSON.stringify(config, null, 2));
+      }
     }
   }
 };
-var mcp = {
-  name: "mcp",
-  group: "MCP",
-  summary: "Print MCP stdio config JSON",
-  synopsis: "mcp",
+var whoami = {
+  name: "whoami",
+  group: "Account",
+  summary: "Show which account and credential the CLI is using",
+  synopsis: "whoami",
   leaf: {
-    summary: "Print MCP stdio config JSON (npx @easybits.cloud/mcp)",
-    usage: "easybits mcp",
-    async run() {
-      console.log(
-        JSON.stringify(
-          {
-            mcpServers: {
-              easybits: {
-                command: "npx",
-                args: ["-y", "@easybits.cloud/mcp"],
-                env: { EASYBITS_API_KEY: "eb_sk_live_YOUR_KEY" }
-              }
-            }
-          },
-          null,
-          2
-        )
-      );
+    summary: "Show the account email and where the credential comes from",
+    usage: "easybits whoami",
+    examples: ["easybits whoami", "easybits whoami --json"],
+    async run(ctx) {
+      const source = process.env.EASYBITS_API_KEY ? "env EASYBITS_API_KEY" : ctx.token ? "--token" : readRc().oauth?.accessToken ? "browser session (~/.easybitsrc)" : readRc().apiKey ? "API key (~/.easybitsrc)" : void 0;
+      if (!source) throw notLoggedIn();
+      const email = await fetchEmail(await resolveCredential(ctx));
+      emit(ctx, { email, source, baseUrl: await resolveBaseUrl3() }, () => console.log(`${email ?? "(unknown email)"}  via ${source}`));
     }
   }
 };
@@ -674,12 +672,12 @@ var files = {
         emit(ctx, data.file, () => console.log(`Uploaded: ${data.file.id}`));
       }
     },
-    delete: {
-      aliases: ["rm"],
+    rm: {
+      aliases: ["delete", "remove"],
       summary: "Delete a file (soft delete, 7-day trash)",
-      usage: "easybits files delete <file-id> [--yes]",
+      usage: "easybits files rm <file-id> [--yes]",
       options: { ...YES_OPTION },
-      examples: ["easybits files delete 6650f0c2a1b2c3d4e5f60718", "easybits files rm 6650f0c2a1b2c3d4e5f60718 --yes"],
+      examples: ["easybits files rm 6650f0c2a1b2c3d4e5f60718", "easybits files rm 6650f0c2a1b2c3d4e5f60718 --yes"],
       async run(ctx) {
         const id = need(ctx, 0, "file-id", this.usage);
         requireYesIfHeadless(ctx);
@@ -992,11 +990,11 @@ function printSandbox(s) {
   if (s.tier) console.log(`Tier:      ${s.tier}${s.monthlyMxn != null ? ` ($${s.monthlyMxn} MXN/month)` : ""}`);
 }
 async function sandbox(ctx, usage2) {
-  const id = need(ctx, 0, "sandbox-id", usage2);
+  const id = need(ctx, 0, "sandbox", usage2);
   const eb = await getClient(ctx);
   return eb.sandboxes.get(id);
 }
-var FILES_USAGE = "easybits sandboxes files <ls|read|write> <sandbox-id> <path> [local-file]";
+var FILES_USAGE = "easybits sandboxes files <ls|read|write> <sandbox> <path> [local-file]";
 var sandboxes = {
   name: "sandboxes",
   aliases: ["sandbox", "sb"],
@@ -1026,11 +1024,11 @@ var sandboxes = {
     create: {
       aliases: ["new"],
       summary: "Create a sandbox and wait until it is running",
-      usage: "easybits sandboxes create [--template ubuntu] [--name <name>] [--timeout <s>] [--size s|m|l|xl] [--dotenv <path>] [--env K=V]...",
+      usage: "easybits sandboxes create [--template ubuntu] [--name <name>] [--ttl <s>] [--size s|m|l|xl] [--dotenv <path>] [--env K=V]...",
       options: {
         template: { type: "string", value: "name", description: "Base template (default ubuntu): ubuntu, python, node, code-interpreter\u2026" },
         name: { type: "string", value: "name", description: "Human label (lets you `ssh <name>.ghosty`)" },
-        timeout: { type: "string", value: "seconds", description: "Time to live before auto-destroy" },
+        ttl: { type: "string", value: "seconds", description: "Time to live before auto-destroy (was --timeout)" },
         size: { type: "string", value: "s|m|l|xl", description: "VM size class (gated by plan)" },
         env: { type: "string", multiple: true, value: "K=V", description: "Environment variable, non-secret (repeatable)" },
         ...ENV_FILE_OPTION,
@@ -1049,7 +1047,7 @@ var sandboxes = {
         const sb = await eb.sandboxes.create({
           template: str(ctx, "template") ?? "ubuntu",
           name: str(ctx, "name"),
-          timeoutSeconds: int(ctx, "timeout", this.usage),
+          timeoutSeconds: int(ctx, "ttl", this.usage),
           size,
           env: Object.keys(env).length ? env : void 0,
           waitForReady: !bool(ctx, "no-wait")
@@ -1061,7 +1059,7 @@ var sandboxes = {
     get: {
       aliases: ["show", "status"],
       summary: "Show one sandbox",
-      usage: "easybits sandboxes get <sandbox-id>",
+      usage: "easybits sandboxes get <sandbox>",
       examples: ["easybits sandboxes get sb_abc123"],
       async run(ctx) {
         const rec = sandboxRecord(await sandbox(ctx, this.usage));
@@ -1070,7 +1068,7 @@ var sandboxes = {
     },
     exec: {
       summary: "Run a shell command inside a sandbox",
-      usage: "easybits sandboxes exec <sandbox-id> [--cwd <dir>] [--timeout <s>] [--dotenv <path>] -- <command...>",
+      usage: "easybits sandboxes exec <sandbox> [--cwd <dir>] [--timeout <s>] [--dotenv <path>] -- <command...>",
       options: {
         cwd: { type: "string", value: "dir", description: "Working directory" },
         timeout: { type: "string", value: "seconds", description: "Kill the command after this long" },
@@ -1084,7 +1082,7 @@ var sandboxes = {
         "easybits sb exec sb_abc123 --json -- 'ls -la /' | jq .exitCode"
       ],
       async run(ctx) {
-        need(ctx, 0, "sandbox-id", this.usage);
+        need(ctx, 0, "sandbox", this.usage);
         const command = ctx.args.slice(1).join(" ");
         if (!command) throw usageError("Missing <command>.", this.usage);
         const env = await envFrom(ctx, this.usage);
@@ -1107,7 +1105,7 @@ var sandboxes = {
     },
     logs: {
       summary: "Read the sandbox journal (optionally one systemd unit)",
-      usage: "easybits sandboxes logs <sandbox-id> [--unit <unit>] [--lines <n>] [--since <spec>] [--grep <text>]",
+      usage: "easybits sandboxes logs <sandbox> [--unit <unit>] [--lines <n>] [--since <spec>] [--grep <text>]",
       options: {
         unit: { type: "string", value: "unit", description: "systemd unit to filter" },
         lines: { type: "string", value: "n", description: "Last N lines (default 200)" },
@@ -1142,7 +1140,7 @@ var sandboxes = {
       ],
       async run(ctx) {
         const action = need(ctx, 0, "ls|read|write", FILES_USAGE);
-        const id = need(ctx, 1, "sandbox-id", FILES_USAGE);
+        const id = need(ctx, 1, "sandbox", FILES_USAGE);
         const path = need(ctx, 2, "path", FILES_USAGE);
         const eb = await getClient(ctx);
         const sb = await eb.sandboxes.get(id);
@@ -1186,7 +1184,7 @@ var sandboxes = {
     },
     suspend: {
       summary: "Suspend to disk (frees CPU; TTL paused)",
-      usage: "easybits sandboxes suspend <sandbox-id>",
+      usage: "easybits sandboxes suspend <sandbox>",
       examples: ["easybits sandboxes suspend sb_abc123"],
       async run(ctx) {
         const r = await (await sandbox(ctx, this.usage)).suspend();
@@ -1195,7 +1193,7 @@ var sandboxes = {
     },
     resume: {
       summary: "Wake a suspended sandbox",
-      usage: "easybits sandboxes resume <sandbox-id> [--dotenv <path>] [--env K=V]...",
+      usage: "easybits sandboxes resume <sandbox> [--dotenv <path>] [--env K=V]...",
       options: {
         env: { type: "string", multiple: true, value: "K=V", description: "Rewrite env on wake, non-secret (repeatable)" },
         ...ENV_FILE_OPTION
@@ -1210,11 +1208,11 @@ var sandboxes = {
     destroy: {
       aliases: ["rm", "delete"],
       summary: "Destroy a sandbox (irreversible)",
-      usage: "easybits sandboxes destroy <sandbox-id> [--yes]",
+      usage: "easybits sandboxes destroy <sandbox> [--yes]",
       options: { ...YES_OPTION },
       examples: ["easybits sandboxes destroy sb_abc123", "easybits sb rm sb_abc123 --yes"],
       async run(ctx) {
-        need(ctx, 0, "sandbox-id", this.usage);
+        need(ctx, 0, "sandbox", this.usage);
         requireYesIfHeadless(ctx);
         const sb = await sandbox(ctx, this.usage);
         await confirm(
@@ -1228,7 +1226,7 @@ var sandboxes = {
     },
     snapshot: {
       summary: "Capture a copy-on-write snapshot without stopping the box",
-      usage: "easybits sandboxes snapshot <sandbox-id> [--name <name>]",
+      usage: "easybits sandboxes snapshot <sandbox> [--name <name>]",
       options: { name: { type: "string", value: "name", description: "Snapshot label" } },
       examples: ["easybits sandboxes snapshot sb_abc123 --name before-upgrade"],
       async run(ctx) {
@@ -1240,19 +1238,19 @@ var sandboxes = {
 };
 
 // src/commands/machines.ts
-var SECRETS_USAGE = "easybits machines secrets <ls|set|unset> <machine-id> [--dotenv <path> | NAME]";
+var SECRETS_USAGE = "easybits machines secrets <ls|set|unset> <machine> [--dotenv <path> | NAME]";
 var machines = {
   name: "machines",
-  aliases: ["deploy", "machine"],
+  aliases: ["machine"],
   group: "Hosting",
-  summary: "Permanent machines and their releases (alias: deploy)",
+  summary: "Permanent machines and their releases (easybits deploy <machine> publishes)",
   synopsis: "machines",
   subs: {
     ls: {
       aliases: ["list"],
       summary: "List your permanent machines",
       usage: "easybits machines ls",
-      examples: ["easybits machines ls", "easybits deploy ls --json"],
+      examples: ["easybits machines ls", "easybits machines ls --json"],
       async run(ctx) {
         const eb = await getClient(ctx);
         const rows = (await eb.machines.list()).map(sandboxRecord);
@@ -1268,13 +1266,12 @@ var machines = {
       }
     },
     deploy: {
-      aliases: ["release"],
       summary: "Publish the machine's current app code as a new release",
-      usage: "easybits machines deploy <machine-id> [--message <text>]",
+      usage: "easybits machines deploy <machine> [--message <text>]",
       options: { message: { type: "string", short: "m", value: "text", description: "Release note" } },
-      examples: ['easybits machines deploy sb_abc123 -m "v1.2: fix checkout"'],
+      examples: ['easybits machines deploy shop -m "v1.2: fix checkout"', 'easybits deploy shop -m "v1.2"          # same thing, shorter'],
       async run(ctx) {
-        const id = need(ctx, 0, "machine-id", this.usage);
+        const id = need(ctx, 0, "machine", this.usage);
         const eb = await getClient(ctx);
         const r = await eb.machines.deploy(id, { message: str(ctx, "message") });
         emit(ctx, r, () => console.log(`Release v${r.version} ${r.releaseId} (${r.status}, ${fmtBytes(r.sizeBytes)})`));
@@ -1282,11 +1279,11 @@ var machines = {
     },
     releases: {
       summary: "List releases, newest first",
-      usage: "easybits machines releases <machine-id> [--limit <n>]",
+      usage: "easybits machines releases <machine> [--limit <n>]",
       options: { limit: { type: "string", value: "n", description: "How many" } },
       examples: ["easybits machines releases sb_abc123 --limit 5"],
       async run(ctx) {
-        const id = need(ctx, 0, "machine-id", this.usage);
+        const id = need(ctx, 0, "machine", this.usage);
         const eb = await getClient(ctx);
         const r = await eb.machines.releases(id, { limit: int(ctx, "limit", this.usage) });
         emit(
@@ -1295,21 +1292,21 @@ var machines = {
           () => table(
             r.items.map((x) => ({ ...x, size: fmtBytes(x.sizeBytes), createdAt: fmtDate(x.createdAt) })),
             [["version", "VERSION"], ["releaseId", "ID"], ["status", "STATUS"], ["size", "SIZE"], ["createdAt", "CREATED"], ["message", "MESSAGE"]],
-            "No releases yet. Publish one: easybits machines deploy <machine-id>"
+            "No releases yet. Publish one: easybits machines deploy <machine>"
           )
         );
       }
     },
     logs: {
       summary: "Tail the app's own log",
-      usage: "easybits machines logs <machine-id> [--lines <n>] [--grep <text>]",
+      usage: "easybits machines logs <machine> [--lines <n>] [--grep <text>]",
       options: {
         lines: { type: "string", value: "n", description: "Last N lines" },
         grep: { type: "string", value: "text", description: "Only lines matching" }
       },
       examples: ["easybits machines logs sb_abc123 --lines 100", "easybits machines logs sb_abc123 --grep ERROR"],
       async run(ctx) {
-        const id = need(ctx, 0, "machine-id", this.usage);
+        const id = need(ctx, 0, "machine", this.usage);
         const eb = await getClient(ctx);
         const r = await eb.machines.logs(id, { lines: int(ctx, "lines", this.usage), grep: str(ctx, "grep") });
         emit(ctx, r, () => process.stdout.write(r.output.endsWith("\n") || !r.output ? r.output : r.output + "\n"));
@@ -1317,10 +1314,10 @@ var machines = {
     },
     rollback: {
       summary: "Put a previous release back on the same machine (data untouched)",
-      usage: "easybits machines rollback <machine-id> <release-id>",
+      usage: "easybits machines rollback <machine> <release-id>",
       examples: ["easybits machines rollback sb_abc123 rel_789"],
       async run(ctx) {
-        const id = need(ctx, 0, "machine-id", this.usage);
+        const id = need(ctx, 0, "machine", this.usage);
         const rel = need(ctx, 1, "release-id", this.usage);
         const eb = await getClient(ctx);
         const r = await eb.machines.rollback(id, rel);
@@ -1340,7 +1337,7 @@ var machines = {
       ],
       async run(ctx) {
         const action = need(ctx, 0, "ls|set|unset", SECRETS_USAGE);
-        const id = need(ctx, 1, "machine-id", SECRETS_USAGE);
+        const id = need(ctx, 1, "machine", SECRETS_USAGE);
         const eb = await getClient(ctx);
         if (action === "ls" || action === "list") {
           const r = await eb.machines.secrets(id);
@@ -1368,7 +1365,7 @@ var machines = {
 
 // src/commands/domains.ts
 async function sandbox2(ctx, usage2) {
-  const id = need(ctx, 0, "sandbox-id", usage2);
+  const id = need(ctx, 0, "sandbox", usage2);
   return (await getClient(ctx)).sandboxes.get(id);
 }
 var domains = {
@@ -1381,7 +1378,7 @@ var domains = {
     ls: {
       aliases: ["list"],
       summary: "List domains attached to a sandbox",
-      usage: "easybits domains ls <sandbox-id>",
+      usage: "easybits domains ls <sandbox>",
       examples: ["easybits domains ls sb_abc123"],
       async run(ctx) {
         const items = await (await sandbox2(ctx, this.usage)).listDomains();
@@ -1390,7 +1387,7 @@ var domains = {
     },
     add: {
       summary: "Attach a domain to a port; prints the DNS record to create",
-      usage: "easybits domains add <sandbox-id> <domain> --port <port>",
+      usage: "easybits domains add <sandbox> <domain> --port <port>",
       options: { port: { type: "string", value: "port", description: "Port inside the sandbox (required)" } },
       examples: ["easybits domains add sb_abc123 shop.example.com --port 3000"],
       async run(ctx) {
@@ -1407,7 +1404,7 @@ var domains = {
     },
     verify: {
       summary: "Check DNS + HTTPS for a domain",
-      usage: "easybits domains verify <sandbox-id> <domain>",
+      usage: "easybits domains verify <sandbox> <domain>",
       examples: ["easybits domains verify sb_abc123 shop.example.com"],
       async run(ctx) {
         const domain = need(ctx, 1, "domain", this.usage);
@@ -1423,11 +1420,11 @@ var domains = {
     rm: {
       aliases: ["remove", "delete"],
       summary: "Detach a domain",
-      usage: "easybits domains rm <sandbox-id> <domain> [--yes]",
+      usage: "easybits domains rm <sandbox> <domain> [--yes]",
       options: { ...YES_OPTION },
       examples: ["easybits domains rm sb_abc123 shop.example.com", "easybits domains rm sb_abc123 shop.example.com --yes"],
       async run(ctx) {
-        need(ctx, 0, "sandbox-id", this.usage);
+        need(ctx, 0, "sandbox", this.usage);
         const domain = need(ctx, 1, "domain", this.usage);
         requireYesIfHeadless(ctx);
         await confirm(ctx, `Detach ${domain} from ${ctx.args[0]}? It stops serving right away.`);
@@ -1438,16 +1435,104 @@ var domains = {
   }
 };
 
+// src/refs.ts
+var ID_FORMAT = {
+  agent: /^[0-9a-f]{24}$/i,
+  db: /^[0-9a-f]{24}$/i,
+  sandbox: /^sb_[0-9a-z-]+$/i
+};
+var looksLikeId = (kind, ref) => ID_FORMAT[kind].test(ref);
+var REF_ARGS = {
+  "agents get": { index: 0, kind: "agent" },
+  "agents message": { index: 0, kind: "agent" },
+  "agents destroy": { index: 0, kind: "agent" },
+  "sandboxes get": { index: 0, kind: "sandbox" },
+  "sandboxes exec": { index: 0, kind: "sandbox" },
+  "sandboxes logs": { index: 0, kind: "sandbox" },
+  "sandboxes files": { index: 1, kind: "sandbox" },
+  "sandboxes suspend": { index: 0, kind: "sandbox" },
+  "sandboxes resume": { index: 0, kind: "sandbox" },
+  "sandboxes destroy": { index: 0, kind: "sandbox" },
+  "sandboxes snapshot": { index: 0, kind: "sandbox" },
+  "machines deploy": { index: 0, kind: "sandbox" },
+  "machines releases": { index: 0, kind: "sandbox" },
+  "machines logs": { index: 0, kind: "sandbox" },
+  "machines rollback": { index: 0, kind: "sandbox" },
+  "machines secrets": { index: 1, kind: "sandbox" },
+  "domains ls": { index: 0, kind: "sandbox" },
+  "domains add": { index: 0, kind: "sandbox" },
+  "domains verify": { index: 0, kind: "sandbox" },
+  "domains rm": { index: 0, kind: "sandbox" },
+  "db rm": { index: 0, kind: "db" },
+  "db tables": { index: 0, kind: "db" },
+  "db query": { index: 0, kind: "db" }
+};
+function matchRef(kind, ref, items) {
+  if (looksLikeId(kind, ref)) return { ok: true, id: ref };
+  const list2 = items ?? [];
+  if (list2.some((x) => x.id === ref)) return { ok: true, id: ref };
+  const want = ref.trim().toLowerCase();
+  const matches = list2.filter((x) => (x.name ?? "").trim().toLowerCase() === want);
+  if (matches.length === 1) return { ok: true, id: matches[0].id };
+  if (matches.length === 0) return { ok: false, reason: "not_found" };
+  return { ok: false, reason: "ambiguous", matches };
+}
+
+// src/resolve.ts
+var LS_HINT = {
+  agent: "easybits agents ls",
+  sandbox: "easybits sandboxes ls",
+  db: "easybits db ls"
+};
+var NOUN = { agent: "agent", sandbox: "sandbox or machine", db: "database" };
+var cache = /* @__PURE__ */ new Map();
+function listRefs(ctx, kind) {
+  let p = cache.get(kind);
+  if (!p) {
+    p = (async () => {
+      const eb = await getClient(ctx);
+      if (kind === "agent") return (await eb.listAgents()).map((a) => ({ id: a.agentId, name: a.name, status: a.status }));
+      if (kind === "db") return (await eb.listDatabases()).items.map((d) => ({ id: d.id, name: d.name }));
+      return (await eb.sandboxes.list()).map((s) => ({ id: s.sandboxId, name: s.name, status: s.status }));
+    })();
+    p.catch(() => cache.delete(kind));
+    cache.set(kind, p);
+  }
+  return p;
+}
+async function resolveRef(ctx, kind, ref) {
+  if (looksLikeId(kind, ref)) return ref;
+  const r = matchRef(kind, ref, await listRefs(ctx, kind));
+  if (r.ok) return r.id;
+  if (r.reason === "not_found") {
+    throw new CliError(`No ${NOUN[kind]} with id or name "${ref}".`, EXIT.API, `List them with: ${LS_HINT[kind]}`, "not_found", 404);
+  }
+  const shown = r.matches.slice(0, 10).map((m) => `  ${m.id}${m.status ? `  (${m.status})` : ""}`);
+  if (r.matches.length > 10) shown.push(`  \u2026and ${r.matches.length - 10} more`);
+  throw new CliError(
+    `"${ref}" matches ${r.matches.length} ${kind === "db" ? "databases" : `${kind}s`}. Use the id:`,
+    EXIT.USAGE,
+    `${shown.join("\n")}
+List them with: ${LS_HINT[kind]}`,
+    "ambiguous"
+  );
+}
+async function resolveRefs(ctx, key) {
+  const spec = REF_ARGS[key];
+  const ref = spec ? ctx.args[spec.index] : void 0;
+  if (!spec || !ref) return;
+  ctx.args[spec.index] = await resolveRef(ctx, spec.kind, ref);
+}
+
 // src/commands/db.ts
-async function findDb(eb, ref) {
-  const { items } = await eb.listDatabases();
-  const hit = items.find((d) => d.id === ref) ?? items.find((d) => d.name === ref);
-  if (!hit) throw new CliError(`No database "${ref}".`, 1, "List them with: easybits db ls", "not_found", 404);
-  return hit;
+async function findDb(ctx, id) {
+  const hit = (await listRefs(ctx, "db")).find((d) => d.id === id);
+  if (!hit) throw new CliError(`No database "${id}".`, 1, "List them with: easybits db ls", "not_found", 404);
+  return { id, name: hit.name ?? id };
 }
 var db = {
   name: "db",
-  aliases: ["databases"],
+  aliases: ["databases", "database"],
   group: "Data",
   summary: "SQL databases (libSQL)",
   synopsis: "db",
@@ -1493,7 +1578,7 @@ var db = {
         const ref = need(ctx, 0, "db-id|name", this.usage);
         requireYesIfHeadless(ctx);
         const eb = await getClient(ctx);
-        const hit = await findDb(eb, ref);
+        const hit = await findDb(ctx, ref);
         await confirm(ctx, `Delete database ${hit.name} (${hit.id}) and all its data?`, { typeName: hit.name });
         const r = await eb.deleteDatabase(hit.id);
         emit(ctx, { ...r, id: hit.id, name: hit.name }, () => console.log(`Deleted ${hit.name} (${hit.id})`));
@@ -1508,7 +1593,7 @@ var db = {
       async run(ctx) {
         const ref = need(ctx, 0, "db-id|name", this.usage);
         const eb = await getClient(ctx);
-        const hit = await findDb(eb, ref);
+        const hit = await findDb(ctx, ref);
         const q = (sql, args) => eb.queryDatabase(hit.id, sql, args);
         const names = (await q("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_litestream_%' ORDER BY name")).rows.map((r) => String(r[0]));
         const ident = (n) => `"${n.replace(/"/g, '""')}"`;
@@ -1549,7 +1634,7 @@ var db = {
         const ref = need(ctx, 0, "db-id|name", this.usage);
         const sql = need(ctx, 1, "sql", this.usage);
         const eb = await getClient(ctx);
-        const hit = await findDb(eb, ref);
+        const hit = await findDb(ctx, ref);
         const args = list(ctx, "arg");
         const r = await eb.queryDatabase(hit.id, sql, args.length ? args : void 0);
         emit(ctx, r, () => {
@@ -1595,6 +1680,27 @@ var agents = {
         );
       }
     },
+    get: {
+      aliases: ["show"],
+      summary: "Show one agent (by id or name)",
+      usage: "easybits agents get <agent>",
+      examples: ["easybits agents get helper", "easybits agents get 6650f0c2a1b2c3d4e5f60718 --json"],
+      async run(ctx) {
+        const id = need(ctx, 0, "agent", this.usage);
+        const eb = await getClient(ctx);
+        const a = await eb.getAgent(id);
+        emit(ctx, a, () => {
+          console.log(`ID:        ${a.agentId}`);
+          if (a.name) console.log(`Name:      ${a.name}`);
+          console.log(`Template:  ${a.template}`);
+          console.log(`Status:    ${a.status}`);
+          console.log(`Sandbox:   ${a.sandboxId}`);
+          console.log(`URL:       ${a.agentUrl}`);
+          console.log(`Created:   ${fmtDate(a.createdAt)}`);
+          console.log(`Expires:   ${a.expiresAt ? fmtDate(a.expiresAt) : "never"}`);
+        });
+      }
+    },
     create: {
       summary: "Create an agent from a template",
       usage: "easybits agents create --template <template> [--name <name>] [--dotenv <path>] [--env K=V]... [--timeout <s>]",
@@ -1631,12 +1737,12 @@ var agents = {
     },
     message: {
       aliases: ["msg", "send"],
-      summary: "Send a message; streams the reply",
-      usage: "easybits agents message <agent-id> <text...> [--session <id>]",
+      summary: "Send a message (agent by id or name); streams the reply",
+      usage: "easybits agents message <agent> <text...> [--session <id>]",
       options: { session: { type: "string", value: "id", description: "Continue a conversation" } },
-      examples: ['easybits agents message ag_123 "summarize /data/work/README.md"', "easybits agents message ag_123 hi --json"],
+      examples: ['easybits agents message helper "summarize /data/work/README.md"', "easybits agents message 6650f0c2a1b2c3d4e5f60718 hi --json"],
       async run(ctx) {
-        const id = need(ctx, 0, "agent-id", this.usage);
+        const id = need(ctx, 0, "agent", this.usage);
         const content = ctx.args.slice(1).join(" ");
         if (!content) throw usageError("Missing <text>.", this.usage);
         const eb = await getClient(ctx);
@@ -1653,11 +1759,11 @@ var agents = {
     destroy: {
       aliases: ["rm", "delete"],
       summary: "Destroy an agent and its sandbox",
-      usage: "easybits agents destroy <agent-id> [--yes]",
+      usage: "easybits agents destroy <agent> [--yes]",
       options: { ...YES_OPTION },
-      examples: ["easybits agents destroy ag_123            # asks you to type the id", "easybits agents destroy ag_123 --yes"],
+      examples: ["easybits agents destroy helper            # asks you to type the id", "easybits agents destroy helper --yes"],
       async run(ctx) {
-        const id = need(ctx, 0, "agent-id", this.usage);
+        const id = need(ctx, 0, "agent", this.usage);
         requireYesIfHeadless(ctx);
         await confirm(ctx, `Destroy agent ${id} and its sandbox (including /data)?`, { typeName: id });
         const eb = await getClient(ctx);
@@ -1718,6 +1824,7 @@ var docs = {
 var COMMANDS = [
   login,
   logout,
+  whoami,
   usage,
   sandboxes,
   agents,
@@ -1728,7 +1835,6 @@ var COMMANDS = [
   files,
   websites,
   providers,
-  config,
   mcp,
   sshKey,
   sshProxy,
@@ -1770,7 +1876,13 @@ var GLOBAL_FLAGS = `Global flags:
   -h, --help       Help (also: easybits <command> --help)
   -v, --version    Print the CLI version
 
-Deletes (sandboxes destroy, agents destroy, db rm, domains rm, files delete) ask first;
+Naming (like gh): noun then verb \u2014 easybits <noun> <verb>. Old spellings still work
+and print the new one on stderr (never with --json).
+
+Names or ids: agents, sandboxes/machines and databases take either
+(exact, case-insensitive; two with the same name \u2192 exit 2 with the ids).
+
+Deletes (sandboxes destroy, agents destroy, db rm, domains rm, files rm) ask first;
 without a terminal or with --json pass -y/--yes, or they exit 2.
 
 Env: EASYBITS_API_KEY (API key), EASYBITS_URL (API server, default https://www.easybits.cloud)
@@ -1830,7 +1942,71 @@ var BANNER = "            \x1B[38;2;244;245;251m\u2860\u2812\u2812\u28E4\x1B[38;
 
 // src/index.ts
 import { EasybitsError as EasybitsError2 } from "@easybits.cloud/sdk";
-var VERSION = true ? "0.6.1" : "dev";
+
+// src/aliases.ts
+function positionals(argv2) {
+  const out = [];
+  for (let i = 0; i < argv2.length; i++) {
+    const a = argv2[i];
+    if (a === "--") break;
+    if (a === "--token") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("-") && a !== "-") continue;
+    out.push(i);
+  }
+  return out;
+}
+var MACHINE_SUBS = ["ls", "list", "deploy", "release", "releases", "logs", "rollback", "secrets"];
+var SANDBOX_NAMES = ["sandboxes", "sandbox", "sb"];
+function normalizeArgs(input) {
+  const argv2 = [...input];
+  const notes = [];
+  const end = argv2.indexOf("--");
+  const head = end === -1 ? argv2 : argv2.slice(0, end);
+  const help = head.includes("--help") || head.includes("-h");
+  let pos = positionals(argv2);
+  const at = (n) => pos[n] != null ? argv2[pos[n]] : void 0;
+  if (at(0) === "config") {
+    argv2.splice(pos[0], 1, "mcp", "config");
+    notes.push("`easybits config` is now `easybits mcp config`.");
+  } else if (at(0) === "mcp" && at(1) == null && !help) {
+    argv2.splice(pos[0] + 1, 0, "config");
+    argv2.push("--stdio");
+    notes.push("`easybits mcp` is now `easybits mcp config --stdio`.");
+  }
+  if (at(0) === "deploy") {
+    const sub = at(1);
+    if (sub && MACHINE_SUBS.includes(sub) && sub !== "deploy") {
+      argv2[pos[0]] = "machines";
+      notes.push(`\`easybits deploy ${sub}\` is now \`easybits machines ${sub}\`.`);
+    } else if (sub === "deploy") {
+      argv2[pos[0]] = "machines";
+      notes.push("`easybits deploy deploy` is now `easybits deploy <machine>`.");
+    } else {
+      argv2.splice(pos[0], 1, "machines", "deploy");
+    }
+    pos = positionals(argv2);
+  }
+  if ((at(0) === "machines" || at(0) === "machine") && at(1) === "release") {
+    argv2[pos[1]] = "deploy";
+    notes.push("`machines release` is now `machines deploy`.");
+  }
+  if (SANDBOX_NAMES.includes(at(0) ?? "") && (at(1) === "create" || at(1) === "new")) {
+    const stop = argv2.indexOf("--");
+    for (let i = 0; i < (stop === -1 ? argv2.length : stop); i++) {
+      if (argv2[i] === "--timeout" || argv2[i].startsWith("--timeout=")) {
+        argv2[i] = argv2[i].replace("--timeout", "--ttl");
+        notes.push("`sandboxes create --timeout` is now `--ttl` (`--timeout` stays for `exec`).");
+      }
+    }
+  }
+  return { argv: argv2, notes };
+}
+
+// src/index.ts
+var VERSION = true ? "0.8.0" : "dev";
 var GLOBAL_OPTIONS = {
   json: { type: "boolean" },
   token: { type: "string" },
@@ -1862,13 +2038,13 @@ function positionalIndexes(argv2) {
 function parse(argv2, skip, leaf) {
   const rest = argv2.filter((_, i) => !skip.includes(i));
   try {
-    const { values, positionals } = parseArgs({
+    const { values, positionals: positionals2 } = parseArgs({
       args: rest,
       options: { ...GLOBAL_OPTIONS, ...leaf?.options ?? {} },
       allowPositionals: true,
       strict: true
     });
-    return { values, positionals };
+    return { values, positionals: positionals2 };
   } catch (e) {
     throw usageError(e.message.split("\n")[0].split(". To specify")[0].replace(/\.?$/, "."), leaf?.usage);
   }
@@ -1892,7 +2068,15 @@ function unknownSub(cmd, name) {
 ${e.hint}`;
   return e;
 }
-async function main(argv2) {
+function aliasNote(note) {
+  const dim = process.stderr.isTTY && !process.env.NO_COLOR;
+  process.stderr.write(dim ? `\x1B[2m${note}\x1B[0m
+` : `${note}
+`);
+}
+async function main(input) {
+  const { argv: argv2, notes } = normalizeArgs(input);
+  if (!wantsJson(argv2)) notes.forEach(aliasNote);
   const pos = positionalIndexes(argv2);
   const cmdName = pos.length ? argv2[pos[0]] : void 0;
   if (!cmdName || cmdName === "help") {
@@ -1922,22 +2106,25 @@ async function main(argv2) {
   const cmd = findCommand(cmdName);
   if (!cmd) throw unknownCommand(cmdName);
   let leaf = cmd.leaf;
+  let subKey;
   const skip = [pos[0]];
   if (cmd.subs) {
     const subName = pos[1] != null ? argv2[pos[1]] : void 0;
     const entry = subName ? findSub(cmd, subName) : void 0;
     if (entry) {
       leaf = entry[1];
+      subKey = entry[0];
       skip.push(pos[1]);
     } else if (subName) {
       throw unknownSub(cmd, subName);
     } else if (cmd.defaultSub && !argv2.includes("--help") && !argv2.includes("-h")) {
       leaf = cmd.subs[cmd.defaultSub];
+      subKey = cmd.defaultSub;
     } else if (!argv2.includes("--help") && !argv2.includes("-h")) {
       throw usageError(`Missing subcommand for "${cmd.name}".`, `easybits ${cmd.name} <${Object.keys(cmd.subs).join("|")}>`);
     }
   }
-  const { values, positionals } = parse(argv2, skip, leaf);
+  const { values, positionals: positionals2 } = parse(argv2, skip, leaf);
   if (values.version) {
     console.log(VERSION);
     return;
@@ -1949,14 +2136,20 @@ async function main(argv2) {
   const ctx = {
     json: values.json === true,
     token: typeof values.token === "string" ? values.token : void 0,
-    args: positionals,
+    args: positionals2,
     opts: values
   };
+  const refKey = `${cmd.name} ${subKey ?? ""}`.trim();
+  const target = leaf;
+  const run = async () => {
+    await resolveRefs(ctx, refKey);
+    await target.run.call(target, ctx);
+  };
   try {
-    await leaf.run.call(leaf, ctx);
+    await run();
   } catch (e) {
     if (e instanceof EasybitsError2 && e.status === 401 && usedSession() && await forceRefresh()) {
-      await leaf.run.call(leaf, ctx);
+      await run();
       return;
     }
     throw e;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easybits.cloud/cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Official CLI for EasyBits, the cloud for AI agents — sandboxes, hosting, domains, databases, agents and files from your terminal",
   "type": "module",
   "bin": {