dockup-cli 1.0.2 → 1.2.0

package/dist/lib/config.js

@@ -1,176 +1,169 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var config_exports = {};
+__export(config_exports, {
+  clearCurrentWorkspace: () => clearCurrentWorkspace,
+  clearToken: () => clearToken,
+  default: () => config_default,
+  getApiUrl: () => getApiUrl,
+  getCurrentWorkspace: () => getCurrentWorkspace,
+  getProjectConfig: () => getProjectConfig,
+  getToken: () => getToken,
+  getUser: () => getUser,
+  isLoggedIn: () => isLoggedIn,
+  removeProjectConfig: () => removeProjectConfig,
+  saveProjectConfig: () => saveProjectConfig,
+  setApiUrl: () => setApiUrl,
+  setCurrentWorkspace: () => setCurrentWorkspace,
+  setToken: () => setToken,
+  setUser: () => setUser
 });
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getToken = getToken;
-exports.setToken = setToken;
-exports.clearToken = clearToken;
-exports.getUser = getUser;
-exports.setUser = setUser;
-exports.getApiUrl = getApiUrl;
-exports.getCurrentWorkspace = getCurrentWorkspace;
-exports.setCurrentWorkspace = setCurrentWorkspace;
-exports.clearCurrentWorkspace = clearCurrentWorkspace;
-exports.setApiUrl = setApiUrl;
-exports.getProjectConfig = getProjectConfig;
-exports.saveProjectConfig = saveProjectConfig;
-exports.removeProjectConfig = removeProjectConfig;
-exports.isLoggedIn = isLoggedIn;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const os = __importStar(require("os"));
-// Config file path: ~/.dockup/config.json
-const CONFIG_DIR = path.join(os.homedir(), '.dockup');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
-// Ensure config directory exists
+module.exports = __toCommonJS(config_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+const CONFIG_DIR = path.join(os.homedir(), ".dockup");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 function ensureConfigDir() {
-    if (!fs.existsSync(CONFIG_DIR)) {
-        fs.mkdirSync(CONFIG_DIR, { recursive: true });
-    }
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
 }
-// Read config file
 function readConfig() {
-    ensureConfigDir();
-    if (!fs.existsSync(CONFIG_FILE)) {
-        return {};
-    }
-    try {
-        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
-    }
-    catch {
-        return {};
-    }
-}
-// Write config file
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
 function writeConfig(data) {
-    ensureConfigDir();
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
 }
-// Simple config object that mimics Conf API
 const config = {
-    get(key) {
-        const data = readConfig();
-        return data[key];
-    },
-    set(key, value) {
-        const data = readConfig();
-        data[key] = value;
-        writeConfig(data);
-    },
-    delete(key) {
-        const data = readConfig();
-        delete data[key];
-        writeConfig(data);
-    },
-    clear() {
-        writeConfig({});
-    }
+  get(key) {
+    const data = readConfig();
+    return data[key];
+  },
+  set(key, value) {
+    const data = readConfig();
+    data[key] = value;
+    writeConfig(data);
+  },
+  delete(key) {
+    const data = readConfig();
+    delete data[key];
+    writeConfig(data);
+  },
+  clear() {
+    writeConfig({});
+  }
 };
-// Get API token
 function getToken() {
-    return config.get('token');
+  return config.get("token");
 }
-// Set API token
 function setToken(token) {
-    config.set('token', token);
+  config.set("token", token);
 }
-// Clear token (logout)
 function clearToken() {
-    config.delete('token');
-    config.delete('user');
-    config.delete('currentWorkspace');
+  config.delete("token");
+  config.delete("user");
+  config.delete("currentWorkspace");
 }
-// Get current user
 function getUser() {
-    return config.get('user');
+  return config.get("user");
 }
-// Set current user
 function setUser(user) {
-    config.set('user', user);
+  config.set("user", user);
 }
-// Get API URL
 function getApiUrl() {
-    return config.get('apiUrl') || 'https://app.dockup.ai/api';
+  return config.get("apiUrl") || "https://app.dockup.ai/api";
 }
-// Get current workspace
 function getCurrentWorkspace() {
-    return config.get('currentWorkspace');
+  return config.get("currentWorkspace");
 }
-// Set current workspace
 function setCurrentWorkspace(workspace) {
-    config.set('currentWorkspace', workspace);
+  config.set("currentWorkspace", workspace);
 }
-// Clear current workspace
 function clearCurrentWorkspace() {
-    config.delete('currentWorkspace');
+  config.delete("currentWorkspace");
 }
-// Set API URL (for development)
 function setApiUrl(url) {
-    config.set('apiUrl', url);
+  config.set("apiUrl", url);
 }
-// Project-level config stored in .dockup file
-const PROJECT_CONFIG_FILE = '.dockup';
-// Get project config from current directory
+const PROJECT_CONFIG_FILE = ".dockup";
 function getProjectConfig() {
-    const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
-    if (!fs.existsSync(configPath)) {
-        return null;
-    }
-    try {
-        const content = fs.readFileSync(configPath, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch {
-        return null;
-    }
-}
-// Save project config to current directory
+  const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
 function saveProjectConfig(projectConfig) {
-    const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
-    fs.writeFileSync(configPath, JSON.stringify(projectConfig, null, 2));
+  const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
+  fs.writeFileSync(configPath, JSON.stringify(projectConfig, null, 2));
 }
-// Remove project config
 function removeProjectConfig() {
-    const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
-    if (fs.existsSync(configPath)) {
-        fs.unlinkSync(configPath);
-        return true;
-    }
-    return false;
-}
-// Check if logged in
-function isLoggedIn() {
-    return !!getToken();
+  const configPath = path.join(process.cwd(), PROJECT_CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    fs.unlinkSync(configPath);
+    return true;
+  }
+  return false;
 }
-exports.default = config;
+function isLoggedIn() {
+  return !!getToken();
+}
+var config_default = config;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearCurrentWorkspace,
+  clearToken,
+  getApiUrl,
+  getCurrentWorkspace,
+  getProjectConfig,
+  getToken,
+  getUser,
+  isLoggedIn,
+  removeProjectConfig,
+  saveProjectConfig,
+  setApiUrl,
+  setCurrentWorkspace,
+  setToken,
+  setUser
+});

package/dist/lib/flags.js

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var flags_exports = {};
+__export(flags_exports, {
+  isJson: () => isJson,
+  setJson: () => setJson
+});
+module.exports = __toCommonJS(flags_exports);
+let _json = false;
+function setJson(value) {
+  _json = value;
+}
+function isJson() {
+  return _json;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isJson,
+  setJson
+});

package/dist/lib/output.js

@@ -0,0 +1,65 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var output_exports = {};
+__export(output_exports, {
+  emit: () => emit,
+  fail: () => fail,
+  ok: () => ok
+});
+module.exports = __toCommonJS(output_exports);
+var import_chalk = __toESM(require("chalk"));
+var import_flags = require("./flags");
+function emit(data, human) {
+  if ((0, import_flags.isJson)()) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  } else {
+    human();
+  }
+}
+function fail(message, extra = {}) {
+  if ((0, import_flags.isJson)()) {
+    process.stdout.write(JSON.stringify({ ok: false, error: message, ...extra }, null, 2) + "\n");
+  } else {
+    console.error(import_chalk.default.red(message));
+  }
+  process.exit(1);
+}
+function ok(data, human) {
+  if ((0, import_flags.isJson)()) {
+    process.stdout.write(JSON.stringify({ ok: true, ...data }, null, 2) + "\n");
+  } else {
+    human();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  emit,
+  fail,
+  ok
+});

package/dist/lib/target.js

@@ -0,0 +1,40 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var target_exports = {};
+__export(target_exports, {
+  resolveTarget: () => resolveTarget
+});
+module.exports = __toCommonJS(target_exports);
+var import_config = require("./config");
+function resolveTarget(arg) {
+  if (arg && arg.includes("/")) {
+    const [projectSlug, serviceSlug] = arg.split("/");
+    if (projectSlug && serviceSlug) return { projectSlug, serviceSlug };
+  }
+  if (arg && !arg.includes("/")) {
+    throw new Error(`Invalid target "${arg}". Use the form "project/service".`);
+  }
+  const cfg = (0, import_config.getProjectConfig)();
+  if (cfg) return { projectSlug: cfg.projectSlug, serviceSlug: cfg.serviceSlug };
+  throw new Error('No target. Pass "project/service" or run `dockup link` in the project directory.');
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveTarget
+});

package/dockupcli.md

@@ -0,0 +1,211 @@
+# Dockup CLI — Guide for AI Agents
+
+`dockup` is a command-line tool for the Dockup deploy platform. It lets an agent
+inspect and manage deployed services entirely through **bash**: read/write env
+vars, check deploy status, browse deployment history, read logs, and trigger
+deploys.
+
+**Golden rule for agents:** pass `--json` (or `-j`) to **every** command. You get
+structured JSON on stdout; on error you get `{"ok":false,"error":"...","code":"..."}`
+and a non-zero exit code. Without `--json` you get human-formatted text.
+
+---
+
+## Install & auth
+
+```bash
+npm install -g dockup-cli      # or: node /path/to/cli/dist/index.js
+dockup login                   # opens app.dockup.ai/cli-auth → paste the long-lived token
+dockup login -t <TOKEN>        # non-interactive (agents): pass the token directly
+dockup whoami --json           # verify auth → {"id","email","name"}
+```
+
+The token is stored in `~/.dockup/config.json` and never expires.
+
+---
+
+## Targeting a service
+
+Most commands take an optional **`project/service`** argument (both are slugs):
+
+```bash
+dockup info my-project/my-api --json
+```
+
+If omitted, the CLI uses the **linked service** from a `.dockup` file in the
+current directory (created by `dockup link`). For env commands the target is the
+`-s, --service <project/service>` flag instead of a positional arg.
+
+Discover valid targets with `dockup services --json` (the `target` field is
+exactly the `project/service` string to use everywhere else).
+
+---
+
+## Commands
+
+### Discovery
+
+```bash
+dockup services --json
+# → {"count":N,"services":[{"target":"proj/svc","name","project","status","domain","branch","deploymentType","countryCode"}]}
+
+dockup info my-project/my-api --json
+# → {"target","name","status","deploymentType","repoUrl","branch","domain","port",
+#    "exposedPort","autoDeployEnabled","prPreviewEnabled","memoryLimit","cpuLimit",
+#    "lastDeployedAt","lastError","env":[{"key","isSecret","value"}],"customDomains":[...],
+#    "latestDeployment":{...}}
+```
+
+### Status & history
+
+```bash
+dockup status my-project/my-api --json
+# → {"target","status","domain","lastDeployedAt","lastError","latestDeployment":{...}}
+
+dockup deployments my-project/my-api -n 20 --json
+# (alias: dockup history)
+# → {"target","count","deployments":[{"id","status","commitHash","commitMessage",
+#    "triggeredBy","startedAt","completedAt","createdAt"}]}
+```
+
+`status` values: `creating | building | deploying | running | stopped | suspended | error`.
+deployment `status`: `pending | cloning | building | deploying | success | failed`.
+
+### Logs
+
+```bash
+dockup logs my-project/my-api --json            # runtime logs (running container/pods)
+dockup logs my-project/my-api -n 500 --json     # more lines
+dockup logs my-project/my-api --build --json    # build logs of the latest deployment
+# runtime → {"target","type":"runtime","logs":"..."}
+# build   → {"target","type":"build","deployment":{...},"lastError":...,"logs":"..."}
+```
+
+When a deploy fails, read `--build` logs to see why.
+
+### Environment variables
+
+Secret **values are never returned** (shown as `null` / `<secret>`); keys and the
+`isSecret` flag are. You can still set/overwrite secrets.
+
+```bash
+dockup env list -s my-project/my-api --json
+# → {"target","count","env":[{"key","isSecret","value"}]}
+
+dockup env set DATABASE_URL=postgres://... -s my-project/my-api --json
+dockup env set API_KEY=sk-123 --secret -s my-project/my-api --json
+dockup env remove OLD_VAR -s my-project/my-api --json
+dockup env import .env -s my-project/my-api --json   # bulk from a .env-style file
+# mutations → {"ok":true,"target","key"/"keys","hint":"redeploy to apply"}
+```
+
+> Env changes only take effect after a redeploy.
+
+### Deploy
+
+```bash
+dockup deploy my-project/my-api --json          # trigger deploy (no git push)
+dockup deploy my-project/my-api -b main --json
+# → {"ok":true,"target","deploymentId","hint":"poll `dockup status` for progress"}
+
+# From inside a linked git repo, git push + deploy + live progress:
+dockup push
+```
+
+After triggering, poll `dockup status ... --json` until
+`latestDeployment.status` is `success` or `failed`.
+
+### Private registry (private FROM base image)
+
+If your Dockerfile starts with `FROM <private-registry>/...` (e.g. a private
+GHCR base image), set credentials so the build host can pull it. The token is
+stored encrypted and never returned by the API.
+
+```bash
+dockup registry set my-project/my-api \
+  --url ghcr.io --user my-org --token "$GHCR_PAT" --json
+# → {"ok":true,"target","registryUrl","registryUsername","hint":"redeploy to use the private base image"}
+
+dockup registry clear my-project/my-api --json
+```
+
+- `--url` is the registry host (`ghcr.io`, `registry.example.com`, …).
+- For GHCR, a PAT with `read:packages` scope is enough.
+- Credentials apply on the next deploy (build runs `docker login` then `docker build`).
+- `dockup info --json` shows `registryUrl`, `registryUsername` and
+  `hasRegistryAuth` (the password is never exposed).
+
+### Resources (reserved CPU & RAM — PRO)
+
+Pick how much CPU and RAM a service or database reserves. Billing follows the
+allocation (≈ $20/vCPU + $10/GB per month + disk). Max **24 vCPU / 24576 MB**.
+
+```bash
+# View current allocation + estimated monthly cost
+dockup resources my-project/my-api --json
+# → {"target","kind":"service","name","cpu","memoryMB","estMonthlyUsd","limits":{"maxCpu":24,"maxMemMB":24576}}
+
+# Set (service). Applied live by recreating the container (no rebuild; data persists).
+dockup resources set my-project/my-api --cpu 2 --memory 4096 --json
+# → {"ok":true,"target","kind":"service","cpu","memoryMB","applied","estMonthlyUsd"}
+
+# Databases: add --db (main-server databases only; recreates the container, volume kept)
+dockup resources my-project/my-db --db --json
+dockup resources set my-project/my-db --db --cpu 1 --memory 2048 --json
+```
+
+- `--cpu` is vCPU (e.g. `0.5`, `2`, `8`); `--memory` is MB (e.g. `512`, `4096`).
+- Values out of range are clamped to `[0.5 vCPU, 512 MB] … [24 vCPU, 24576 MB]`.
+- PRO only — non-PRO accounts get `403 Upgrade required`.
+- `applied:true` means a running container was recreated immediately; otherwise
+  it applies on the next deploy (service) / start (database).
+- `dockup info --json` also surfaces a service's current `memoryLimit`/`cpuLimit`.
+
+---
+
+## Agent recipes
+
+**Find a service and check if it's healthy**
+```bash
+dockup services --json | jq '.services[] | select(.name=="my-api")'
+dockup status my-project/my-api --json | jq -r '.status'
+```
+
+**Deploy and wait for the result**
+```bash
+dockup deploy my-project/my-api --json
+while :; do
+  s=$(dockup status my-project/my-api --json | jq -r '.latestDeployment.status')
+  [ "$s" = "success" ] && { echo "deployed"; break; }
+  [ "$s" = "failed" ]  && { dockup logs my-project/my-api --build --json | jq -r '.logs' | tail -40; exit 1; }
+  sleep 3
+done
+```
+
+**Update config then redeploy**
+```bash
+dockup env set FEATURE_FLAG=on -s my-project/my-api --json
+dockup deploy my-project/my-api --json
+```
+
+**Diagnose a crash**
+```bash
+dockup status  my-project/my-api --json | jq '.lastError'
+dockup logs    my-project/my-api --json | jq -r '.logs' | tail -60       # runtime
+dockup logs    my-project/my-api --build --json | jq -r '.logs' | tail -60  # build
+```
+
+---
+
+## Error handling
+
+- Every command exits non-zero on failure.
+- With `--json`, failures print `{"ok":false,"error":"<message>","code":"<code>"}`.
+  Codes include: `not_logged_in`, `no_target`, `bad_format`, `file_not_found`.
+- 404 "not found" usually means a wrong `project/service` slug — re-run
+  `dockup services --json` to get exact targets.
+
+## Notes & limits
+- `dockup db ...` and `dockup workspace rename/delete` are **not reliable** yet
+  (CLI/server endpoint mismatch) — avoid them in automation.
+- Pretty (non-JSON) output is for humans; agents should always use `--json`.