@figs-so/cli 0.1.6 → 0.1.7

package/README.md

@@ -31,5 +31,8 @@ The full, always-current guide + `agent.json` schema is served at **`<endpoint>/
 | `figs doctor` | validate `.figs/` against the contract |
 | `figs push` | one-way publish of `.figs/` |
 | `figs version` | print version + check for updates |
+| `figs help [<command>]` | usage (bare `figs` shows it too) |
+
+Global: `-h` / `--help` on any command (or `figs help <command>`), `-v` / `--version` for the version. Unknown commands exit non-zero.
 
 Override the endpoint with `FIGS_ENDPOINT` (e.g. `http://localhost:3000` for local dev).

package/figs.mjs

@@ -12,9 +12,11 @@
  *   figs doctor                         validate .figs/ against the contract before pushing
  *   figs push                           one-way push the .figs/ spine to the ingest endpoint
  *   figs version                        print the CLI version (and check for updates)
+ *   figs help [<command>]               usage; `-h`/`--help` on any command, `-v` for version
  *
  * Designed to be driven by an agent: non-interactive, clear output, `--json`
- * on read commands, and errors that say what to do next.
+ * on read commands, `-h`/`--help`/`help` everywhere, and errors that say what to
+ * do next. Bare `figs` prints help; unknown commands exit non-zero.
  *
  * Auth is the *user* (a token, configured once per machine). Identity is the
  * *agent* — a UUID generated by `init`, stored in the committed, non-secret
@@ -33,7 +35,7 @@ import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const VERSION = "0.1.6"
+const VERSION = "0.1.7"
 // Going-forward default; override with FIGS_ENDPOINT or .figs/config.json endpoint
 // (e.g. FIGS_ENDPOINT=http://localhost:3000 for local dev).
 const DEFAULT_ENDPOINT = "https://app.figs.so"
@@ -41,8 +43,39 @@ const DEFAULT_ENDPOINT = "https://app.figs.so"
 const repoDir = join(process.cwd(), ".figs")
 const globalDir = join(homedir(), ".figs")
 const globalCreds = join(globalDir, "credentials.json")
-const cmd = process.argv[2] ?? "status"
+const cmd = process.argv[2] ?? "help"
 const JSON_OUT = process.argv.includes("--json")
+const WANTS_HELP = process.argv.slice(2).some((a) => a === "-h" || a === "--help")
+
+/** Command registry — single source for dispatch + `figs help`. */
+const COMMANDS = {
+  status: { args: "[--json]", desc: "show login / workspace / agent state" },
+  login: {
+    args: "[<token>]",
+    desc: "log in — browser device-flow, or save a pasted token",
+    more: [
+      "no arg → device flow: a human approves in a browser (you never see the token).",
+      "<token> → save a token you already have to ~/.figs/credentials.json.",
+    ],
+  },
+  logout: { args: "", desc: "remove the locally-saved token (~/.figs/credentials.json)" },
+  workspaces: { args: "[--json]", desc: "list your workspaces (read-only; shows the slug)" },
+  init: {
+    args: "--workspace <slug-or-id> [--endpoint <url>]",
+    desc: "set up .figs/ here (identity UUID + config + pointer GUIDE.md)",
+    more: [
+      "--workspace takes a slug (resolved to its UUID) or a raw UUID — get it from `figs workspaces`.",
+    ],
+  },
+  doctor: { args: "", desc: "validate .figs/ against the live contract before pushing" },
+  push: {
+    args: "",
+    desc: "publish .figs/ — spine to /api/ingest, artifacts to /api/artifacts",
+    more: ["Idempotent (records fold by id). Exits non-zero if an artifact upload is rejected."],
+  },
+  version: { args: "", desc: "print the CLI version and check for updates" },
+  help: { args: "[<command>]", desc: "show this help, or detailed help for one command" },
+}
 
 function die(msg) {
   console.error(`figs: ${msg}`)
@@ -144,20 +177,51 @@ async function checkVersion({ force = false, hardFail = false } = {}) {
   }
 }
 
-if (cmd === "login") await login(process.argv[3])
+/** `figs help [cmd]` — top-level usage, or one command's detail. */
+function printHelp(name) {
+  const pad = 36
+  if (name && name !== "-h" && name !== "--help") {
+    const c = COMMANDS[name]
+    if (!c) {
+      console.log(`figs: no such command "${name}"\n`)
+      return printHelp()
+    }
+    console.log(`Usage: figs ${name}${c.args ? " " + c.args : ""}\n`)
+    console.log(`  ${c.desc}`)
+    if (c.more) for (const line of c.more) console.log(`  ${line}`)
+    return
+  }
+  console.log("figs — publish your AI agent's state to Figs (https://figs.so)\n")
+  console.log("Usage: figs <command> [options]\n")
+  console.log("Commands:")
+  for (const [n, c] of Object.entries(COMMANDS)) {
+    console.log(`  ${`${n} ${c.args}`.trim().padEnd(pad)} ${c.desc}`)
+  }
+  console.log("\nGlobal flags:")
+  console.log(`  ${"-h, --help".padEnd(pad)} show help (or \`figs help <command>\`)`)
+  console.log(`  ${"-v, --version".padEnd(pad)} print the CLI version`)
+  console.log("\nEnvironment:")
+  console.log(`  ${"FIGS_ENDPOINT".padEnd(pad)} override the API endpoint (e.g. http://localhost:3000)`)
+  console.log(`  ${"FIGS_TOKEN".padEnd(pad)} use this token instead of ~/.figs/credentials.json`)
+  console.log(`\nEndpoint: ${resolveEndpoint()}`)
+  console.log(`Guide:    ${resolveEndpoint()}/llms.txt`)
+}
+
+if (cmd === "help" || cmd === "-h" || cmd === "--help") printHelp(process.argv[3])
+else if (cmd === "version" || cmd === "--version" || cmd === "-v" || cmd === "-V") {
+  console.log(VERSION)
+  await checkVersion({ force: true })
+} else if (WANTS_HELP) printHelp(cmd)
+else if (cmd === "login") await login(process.argv[3])
 else if (cmd === "logout") logout()
 else if (cmd === "status") await status()
 else if (cmd === "workspaces") await workspaces()
 else if (cmd === "init") await init()
 else if (cmd === "doctor") await doctor()
 else if (cmd === "push") await push()
-else if (cmd === "version" || cmd === "--version") {
-  console.log(VERSION)
-  await checkVersion({ force: true })
-} else {
-  die(
-    `unknown command "${cmd}" — try: status, login, logout, workspaces, init, doctor, push`,
-  )
+else {
+  console.error(`figs: unknown command "${cmd}" — run \`figs help\` for usage`)
+  process.exit(1)
 }
 
 function sleep(ms) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {