@easybits.cloud/cli 0.6.0 → 0.7.0

package/README.md

@@ -17,7 +17,9 @@ Requires Node 22+.
 
 ```bash
 easybits login                       # opens your browser (OAuth2 + PKCE); session renews itself
+easybits login --no-browser          # only print the sign-in URL
 easybits login - < key.txt           # or save an API key, read from stdin (never in argv)
+printenv EB_KEY | easybits login --with-token   # same as -
 easybits usage
 easybits logout
 ```
@@ -25,7 +27,8 @@ easybits logout
 Running a command without a session in a terminal starts the login automatically;
 without a terminal (agents, CI) it exits `3`. Precedence: `EASYBITS_API_KEY` env var >
 `--token <key>` > browser session > saved API key. Keys: https://www.easybits.cloud/dash/developer.
-In CI and agents, `EASYBITS_API_KEY` needs no login at all.
+In CI and agents, `EASYBITS_API_KEY` needs no login at all. `EASYBITS_URL` points the CLI at
+another server (default `https://www.easybits.cloud`; `baseUrl` in `~/.easybitsrc` works too).
 
 ## Commands
 
@@ -33,9 +36,10 @@ In CI and agents, `EASYBITS_API_KEY` needs no login at all.
 # 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 get sb_abc123
 easybits sandboxes exec sb_abc123 -- npm test
-easybits sandboxes logs sb_abc123 --unit myapp --lines 100
+easybits sandboxes logs sb_abc123 --unit myapp --lines 100 --since "10 min ago" --grep ERROR
 easybits sandboxes files ls sb_abc123 /data/work
 easybits sandboxes files read sb_abc123 /etc/os-release
 easybits sandboxes files write sb_abc123 /data/work/app.js ./app.js
@@ -47,8 +51,8 @@ easybits sandboxes destroy sb_abc123 --yes
 # Hosting: permanent machines (alias: deploy)
 easybits machines ls
 easybits machines deploy sb_abc123 -m "v1.2"
-easybits machines releases sb_abc123
-easybits machines logs sb_abc123 --grep ERROR
+easybits machines releases sb_abc123 --limit 5
+easybits machines logs sb_abc123 --lines 100 --grep ERROR
 easybits machines rollback sb_abc123 rel_789
 easybits machines secrets ls sb_abc123
 easybits machines secrets set sb_abc123 --dotenv .env.production   # - reads stdin
@@ -71,14 +75,17 @@ 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 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 websites ls
+easybits providers                   # storage provider (Tigris by default)
 easybits usage
 
 # MCP, SSH, docs
@@ -86,15 +93,20 @@ easybits config        # MCP config (streamable HTTP)
 easybits mcp           # 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
 irreversible ones (a database, an agent, a permanent sandbox). Without a terminal they
-never prompt: pass `--yes` / `-y`, or they exit `2`.
+never prompt — and neither do they with `--json`: pass `--yes` / `-y`, or they exit `2`.
 
 **Secrets** go in a dotenv file or on stdin, never in argv (visible in `ps` and shell
 history): `--dotenv <path>` (`KEY=VALUE` lines, `-` = stdin) on `sandboxes create|exec|resume`,
@@ -116,12 +128,18 @@ Host *.ghosty
 - `--json`: stdout is JSON only, errors included: `{"error":"…","code":3,"hint":"…"}` (`code` = exit code).
 - Exit codes: `0` ok · `1` API error · `2` usage error · `3` no session, expired or rejected.
 - Login for a person: `easybits login --json` prints `{"event":"login_url","url":…}` first (show it to them), then `{"event":"logged_in","email":…}`.
-- Destructive commands need `--yes` (no TTY means no prompt: exit `2` with the exact command to rerun).
+- Destructive commands need `--yes`, also with `--json` (no TTY or `--json` means no prompt: exit `2` with the exact command to rerun).
 - `sandboxes exec` without `--json` exits with the remote command's code; with `--json` it exits 0 and reports `exitCode`.
 - Skill: `npx skills add https://easybits.cloud` (includes `easybits-cli`).
 
 Full reference: https://www.easybits.cloud/docs#cli · https://www.easybits.cloud/en/docs/cli.md
 
+## Changes in 0.6.1
+
+- Help: `--yes` is no longer listed as a global flag; it lives on each destructive command
+  (and the global help says it is required without a terminal or with `--json`).
+- `easybits init` suggests `machines secrets set <id> --dotenv …` instead of `KEY=VALUE` in argv.
+
 ## Changes in 0.6.0
 
 - **Breaking for scripts:** `db rm`, `agents destroy`, `sandboxes destroy`, `domains rm` and

package/dist/index.js

@@ -59,7 +59,7 @@ var KIND_HINTS = {
   SandboxHostTimeout: "The operation may still be running. Check `easybits sb get <id>` and retry in a few minutes.",
   SandboxHostError: "The sandbox host failed. Retry; if it persists, contact support.",
   SQL_ERROR: "Fix the SQL statement.",
-  DATABASE_STORAGE_MISSING: "This database has no storage; its data is unavailable. Delete it (easybits db rm) and create a new one.",
+  DATABASE_STORAGE_MISSING: "This database has no storage; its data is unavailable. Delete it (easybits db rm <db> --yes) and create a new one.",
   DATABASE_BACKEND_ERROR: "The database backend failed. Retry in a moment."
 };
 function toCliError(err) {
@@ -573,7 +573,7 @@ import { basename, extname } from "path";
 // src/prompt.ts
 import { createInterface } from "readline/promises";
 var YES_OPTION = {
-  yes: { type: "boolean", short: "y", description: "Skip the confirmation (required without a terminal)" }
+  yes: { type: "boolean", short: "y", description: "Skip the confirmation (required without a terminal or with --json)" }
 };
 function sameCommand() {
   const argv2 = process.argv.slice(2).map((a) => /^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`);
@@ -877,7 +877,7 @@ One-time setup left:
 
 3. If your app uses secret env vars:
 
-   easybits machines secrets set SANDBOX_ID DATABASE_URL=...
+   easybits machines secrets set SANDBOX_ID --dotenv .env.production
 
 From then on, every push to main deploys.`));
     }
@@ -992,11 +992,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"],
@@ -1061,7 +1061,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 +1070,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 +1084,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 +1107,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 +1142,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 +1186,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 +1195,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 +1210,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 +1228,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,7 +1240,7 @@ 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"],
@@ -1270,11 +1270,11 @@ 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"'],
       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 +1282,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 +1295,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 +1317,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 +1340,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 +1368,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 +1381,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 +1390,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 +1407,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 +1423,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,12 +1438,100 @@ 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",
@@ -1493,7 +1581,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 +1596,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 +1637,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 +1683,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 +1740,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 +1762,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);
@@ -1767,10 +1876,17 @@ ${hits.map((h) => `  ${prefix}${h}`).join("\n")}`;
 var GLOBAL_FLAGS = `Global flags:
   --json           Machine output: JSON on stdout, errors included
   --token <key>    API key for this call (prefer EASYBITS_API_KEY: argv leaks to ps)
-  -y, --yes        On rm/destroy: skip the confirmation (required without a TTY)
   -h, --help       Help (also: easybits <command> --help)
   -v, --version    Print the CLI version
 
+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 delete) 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)
+
 Exit codes: 0 ok, 1 API error, 2 usage error, 3 not logged in or bad key`;
 var COL = 17;
 function globalHelp(version) {
@@ -1826,7 +1942,7 @@ 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.0" : "dev";
+var VERSION = true ? "0.7.0" : "dev";
 var GLOBAL_OPTIONS = {
   json: { type: "boolean" },
   token: { type: "string" },
@@ -1918,17 +2034,20 @@ 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("|")}>`);
     }
@@ -1948,11 +2067,17 @@ async function main(argv2) {
     args: positionals,
     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.0",
+  "version": "0.7.0",
   "description": "Official CLI for EasyBits, the cloud for AI agents — sandboxes, hosting, domains, databases, agents and files from your terminal",
   "type": "module",
   "bin": {