@congressio/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @congressio/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line access to [Congressio](https://congressio.net), a conference
+management platform for call for papers, peer review, program scheduling and
+attendee registration.
+
+Zero dependencies, no build step — it is plain ESM on Node's built-in `fetch`,
+so `npx` resolves and runs it in one download.
+
+```bash
+npx @congressio/cli events list
+```
+
+## Commands
+
+Commands marked **[key]** need an organization API key. The rest need no
+credentials at all.
+
+| Command                                                                                      | What it does                                               |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `congressio events list [--all]`                                                             | Public conference directory                                |
+| `congressio events get <slug>`                                                               | One public conference                                      |
+| `congressio my events [--all]`                                                               | **[key]** Your organization's events, drafts included      |
+| `congressio submissions list --event <id> [--all]`                                           | **[key]** Submissions with status and track                |
+| `congressio registrations list --event <id> [--all]`                                         | **[key]** Confirmed registrations                          |
+| `congressio registrations create --event <id> --name <name> --email <email> [--tier <tier>]` | **[key]** Register an attendee (comped — takes no payment) |
+| `congressio docs [slug]`                                                                     | Documentation as Markdown                                  |
+| `congressio openapi`                                                                         | The OpenAPI 3.1 document                                   |
+
+## Options
+
+| Option             | Effect                                                   |
+| ------------------ | -------------------------------------------------------- |
+| `--json`           | Print the API response verbatim — for scripts and agents |
+| `--all`            | Follow pagination and return every item                  |
+| `--retry`          | On a 429, wait `Retry-After` and try again               |
+| `--api-key <key>`  | Override `CONGRESSIO_API_KEY`                            |
+| `--base-url <url>` | Point at another deployment                              |
+| `--quiet`          | Suppress progress and quota notes                        |
+
+## Authentication
+
+Create a key in Congressio under **Organization settings → API**, pick its
+scopes, then:
+
+```bash
+export CONGRESSIO_API_KEY=cong_live_…
+congressio my events
+```
+
+The secret is shown once at creation and stored only as a hash, so keep it
+somewhere safe — to rotate, create a new key and revoke the old one. A key is
+scoped to one organization and to the scopes you granted it; an operation
+missing its scope is refused with `403 forbidden`.
+
+## Designed to be scripted
+
+- `--json` writes the API payload **unchanged** to stdout. Nothing is reshaped,
+  so the [OpenAPI schema](https://congressio.net/openapi.json) describes exactly
+  what you get.
+- Progress, warnings and quota notes always go to **stderr**, so `--json`
+  output pipes straight into `jq`.
+- Exit codes: `0` success, `1` API error, `2` usage error.
+- The CLI reads the API's `RateLimit-*` headers and reports what is left. With
+  `--retry` it honours `Retry-After` rather than guessing a backoff.
+- If an endpoint is ever deprecated, its `Deprecation`/`Sunset` headers are
+  surfaced as a warning on stderr — a scripted integration finds out before it
+  breaks.
+
+```bash
+# Every conference opening a call for papers, as JSON
+npx @congressio/cli events list --all --json | jq '.data[] | .slug'
+
+# Import attendees from a CSV
+while IFS=, read -r name email; do
+  congressio registrations create --event "$EVENT_ID" --name "$name" --email "$email"
+done < attendees.csv
+```
+
+## Links
+
+- API reference — <https://congressio.net/developers>
+- OpenAPI 3.1 — <https://congressio.net/openapi.json>
+- Guidance for AI agents — <https://congressio.net/llms.txt>
+- Documentation — <https://congressio.net/docs>

package/bin/congressio.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * Entry point for the Congressio CLI.
+ *
+ * Keeps all the I/O and process concerns here — argument parsing, command
+ * dispatch, formatting and HTTP are pure modules under `lib/`, so they can be
+ * unit-tested without spawning a process or touching the network.
+ */
+
+import { parseArgs, resolveConfig } from "../lib/args.mjs";
+import { COMMANDS, UsageError, resolveCommand } from "../lib/commands.mjs";
+import { helpText } from "../lib/help.mjs";
+import { quotaLine } from "../lib/format.mjs";
+import { ApiError } from "../lib/http.mjs";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+function version() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  try {
+    return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"))
+      .version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+async function main(argv) {
+  const parsed = parseArgs(argv);
+  const config = resolveConfig(parsed.flags, process.env);
+
+  if (parsed.flags.version) {
+    process.stdout.write(`${version()}\n`);
+    return 0;
+  }
+
+  const resolved = resolveCommand(
+    parsed.command,
+    parsed.subcommand,
+    parsed.positionals,
+  );
+
+  if (parsed.flags.help || !parsed.command) {
+    process.stdout.write(`${helpText(version())}\n`);
+    return parsed.command || parsed.flags.help ? 0 : 2;
+  }
+
+  if (!resolved) {
+    process.stderr.write(
+      `congressio: unknown command "${[parsed.command, parsed.subcommand]
+        .filter(Boolean)
+        .join(" ")}"\nRun \`congressio --help\` for the command list.\n`,
+    );
+    return 2;
+  }
+
+  const command = COMMANDS[resolved.key];
+
+  if (command.needsKey && !config.apiKey) {
+    process.stderr.write(
+      `congressio: ${resolved.key.replace(":", " ")} needs an API key.\n` +
+        "Set CONGRESSIO_API_KEY (Organization settings → API), or pass --api-key.\n",
+    );
+    return 2;
+  }
+
+  // stderr for everything advisory, so --json stdout stays parseable.
+  const io = {
+    warn: (message) => {
+      if (!config.quiet) process.stderr.write(`${message}\n`);
+    },
+    quota: (rateLimit) => {
+      if (config.quiet) return;
+      const line = quotaLine(rateLimit);
+      if (line) process.stderr.write(`${line}\n`);
+    },
+  };
+
+  const output = await command.run({
+    config,
+    flags: parsed.flags,
+    subject: resolved.subject,
+    io,
+  });
+
+  if (output) process.stdout.write(`${output}\n`);
+  return 0;
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    if (error instanceof UsageError) {
+      process.stderr.write(`congressio: ${error.message}\n`);
+      process.exit(2);
+    }
+    if (error instanceof ApiError) {
+      process.stderr.write(`congressio: ${error.message}\n`);
+      if (error.code) process.stderr.write(`  code: ${error.code}\n`);
+      if (error.hint) process.stderr.write(`  hint: ${error.hint}\n`);
+      if (error.docs) process.stderr.write(`  docs: ${error.docs}\n`);
+      process.exit(1);
+    }
+    process.stderr.write(
+      `congressio: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exit(1);
+  });

package/lib/args.mjs

@@ -0,0 +1,113 @@
+/**
+ * Argument parsing for the Congressio CLI.
+ *
+ * Hand-rolled on purpose. The whole package ships with zero dependencies so
+ * `npx @congressio/cli` is a single download with nothing to audit and no
+ * build step — which matters when the caller is an agent resolving the tool
+ * on the fly. The grammar is small enough that a parser library would be more
+ * code than this.
+ *
+ * Grammar: `congressio <command> [subcommand] [positional] [--flag value]`
+ *   --flag value   |  --flag=value  |  --boolean-flag
+ *   -h / --help, -v / --version
+ * Everything after a bare `--` is left untouched in `rest`.
+ */
+
+/** Flags that are booleans, so `--json next-arg` does not swallow `next-arg`. */
+export const BOOLEAN_FLAGS = new Set([
+  "json",
+  "help",
+  "version",
+  "retry",
+  "no-color",
+  "quiet",
+]);
+
+/**
+ * Parse argv (without `node` and the script path).
+ *
+ * Returns `{ command, subcommand, positionals, flags, rest }`. Unknown flags
+ * are kept rather than rejected here — the command decides what it accepts, so
+ * a typo produces one clear error from one place.
+ */
+export function parseArgs(argv) {
+  const out = {
+    command: null,
+    subcommand: null,
+    positionals: [],
+    flags: {},
+    rest: [],
+  };
+
+  const words = [];
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--") {
+      out.rest = argv.slice(i + 1);
+      break;
+    }
+
+    if (arg === "-h") {
+      out.flags.help = true;
+      continue;
+    }
+    if (arg === "-v") {
+      out.flags.version = true;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+      if (eq !== -1) {
+        out.flags[body.slice(0, eq)] = body.slice(eq + 1);
+        continue;
+      }
+      if (BOOLEAN_FLAGS.has(body)) {
+        out.flags[body] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        // A value-taking flag with nothing after it. Record it as present and
+        // empty; the command reports the missing value with its own wording.
+        out.flags[body] = "";
+        continue;
+      }
+      out.flags[body] = next;
+      i++;
+      continue;
+    }
+
+    words.push(arg);
+  }
+
+  out.command = words[0] ?? null;
+  out.subcommand = words[1] ?? null;
+  out.positionals = words.slice(2);
+  return out;
+}
+
+/**
+ * Resolve configuration from flags then environment, in that order.
+ *
+ * `CONGRESSIO_API_KEY` is read from the environment so a key never has to
+ * appear in a shell history or a process list.
+ */
+export function resolveConfig(flags, env = {}) {
+  const baseUrl = (
+    flags["base-url"] ||
+    env.CONGRESSIO_BASE_URL ||
+    "https://congressio.net"
+  ).replace(/\/+$/, "");
+
+  return {
+    baseUrl,
+    apiKey: flags["api-key"] || env.CONGRESSIO_API_KEY || null,
+    json: flags.json === true,
+    retry: flags.retry === true,
+    quiet: flags.quiet === true,
+  };
+}

package/lib/commands.mjs

@@ -0,0 +1,318 @@
+import { ApiError, request } from "./http.mjs";
+import { asJson, dateRange, quotaLine, table } from "./format.mjs";
+
+/**
+ * The command table.
+ *
+ * Each entry declares what it needs (`needsKey`, `needsEvent`) so the entry
+ * point can refuse early with a precise message instead of making a request
+ * that is certain to 401. `run` returns the text for stdout; anything advisory
+ * goes through `io.warn` to stderr.
+ */
+
+/** Thrown for a usage mistake — the caller's input, not the API's fault. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+function requireFlag(flags, name, hint) {
+  const value = flags[name];
+  if (!value || value === true) {
+    throw new UsageError(`--${name} is required${hint ? ` (${hint})` : ""}`);
+  }
+  return String(value);
+}
+
+/** Page through a collection until the API returns a short page. */
+async function collectAll(path, config, io, { limit = 100, max = 1000 } = {}) {
+  const items = [];
+  let offset = 0;
+  let rateLimit = null;
+  for (;;) {
+    const sep = path.includes("?") ? "&" : "?";
+    const result = await request(
+      `${path}${sep}limit=${limit}&offset=${offset}`,
+      { ...config, onNotice: io.warn },
+    );
+    rateLimit = result.rateLimit;
+    const page = result.data?.data ?? [];
+    items.push(...page);
+    if (page.length < limit || items.length >= max) break;
+    offset += limit;
+  }
+  return { items, rateLimit };
+}
+
+const EVENT_COLUMNS = [
+  { key: "slug", label: "slug" },
+  { key: "name", label: "name" },
+  { label: "dates", value: (e) => dateRange(e.startDate, e.endDate) },
+  { label: "venue", value: (e) => e.venue?.city ?? null },
+  {
+    label: "program",
+    value: (e) => (e.programPublished ? "published" : "draft"),
+  },
+];
+
+export const COMMANDS = {
+  "events:list": {
+    summary: "List public conferences (no API key needed)",
+    usage: "congressio events list [--all] [--json]",
+    needsKey: false,
+    async run({ config, flags, io }) {
+      const { items, rateLimit } =
+        flags.all === true || flags.all === "true"
+          ? await collectAll("/api/v1/public/events", config, io)
+          : await request("/api/v1/public/events", {
+              ...config,
+              onNotice: io.warn,
+            }).then((r) => ({ items: r.data.data, rateLimit: r.rateLimit }));
+
+      io.quota(rateLimit);
+      if (config.json) return asJson({ data: items });
+      if (items.length === 0) return "No public conferences are published.";
+      return table(items, EVENT_COLUMNS);
+    },
+  },
+
+  "events:get": {
+    summary: "Show one public conference by slug (no API key needed)",
+    usage: "congressio events get <slug> [--json]",
+    needsKey: false,
+    async run({ config, subject, io }) {
+      if (!subject) throw new UsageError("a conference slug is required");
+      const { data, rateLimit } = await request(
+        `/api/v1/public/events/${encodeURIComponent(subject)}`,
+        { ...config, onNotice: io.warn },
+      );
+      io.quota(rateLimit);
+      if (config.json) return asJson(data);
+
+      const e = data.data;
+      const rows = [
+        ["name", e.name],
+        ["slug", e.slug],
+        ["dates", dateRange(e.startDate, e.endDate)],
+        ["timezone", e.timezone],
+        [
+          "venue",
+          [e.venue?.name, e.venue?.city, e.venue?.country]
+            .filter(Boolean)
+            .join(", "),
+        ],
+        ["organizer", e.organization?.name],
+        ["program", e.programPublished ? "published" : "not published"],
+        ["url", e.url],
+      ];
+      return table(
+        rows.map(([field, value]) => ({ field, value })),
+        [
+          { key: "field", label: "field" },
+          { key: "value", label: "value" },
+        ],
+      );
+    },
+  },
+
+  "my:events": {
+    summary: "List your organization's events, including drafts",
+    usage: "congressio my events [--all] [--json]",
+    needsKey: true,
+    async run({ config, flags, io }) {
+      const { items, rateLimit } =
+        flags.all === true
+          ? await collectAll("/api/v1/events", config, io)
+          : await request("/api/v1/events", {
+              ...config,
+              onNotice: io.warn,
+            }).then((r) => ({ items: r.data.data, rateLimit: r.rateLimit }));
+
+      io.quota(rateLimit);
+      if (config.json) return asJson({ data: items });
+      if (items.length === 0) return "This organization has no events yet.";
+      return table(items, [
+        { key: "id", label: "id" },
+        { key: "name", label: "name" },
+        { key: "status", label: "status" },
+        { label: "dates", value: (e) => dateRange(e.startDate, e.endDate) },
+      ]);
+    },
+  },
+
+  "submissions:list": {
+    summary: "List an event's submissions",
+    usage: "congressio submissions list --event <eventId> [--all] [--json]",
+    needsKey: true,
+    async run({ config, flags, io }) {
+      const eventId = requireFlag(
+        flags,
+        "event",
+        "an event UUID from `my events`",
+      );
+      const path = `/api/v1/events/${encodeURIComponent(eventId)}/submissions`;
+      const { items, rateLimit } =
+        flags.all === true
+          ? await collectAll(path, config, io)
+          : await request(path, { ...config, onNotice: io.warn }).then((r) => ({
+              items: r.data.data,
+              rateLimit: r.rateLimit,
+            }));
+
+      io.quota(rateLimit);
+      if (config.json) return asJson({ data: items });
+      if (items.length === 0) return "No submissions yet.";
+      return table(items, [
+        { key: "id", label: "id" },
+        { key: "title", label: "title" },
+        { key: "status", label: "status" },
+        { key: "track", label: "track" },
+      ]);
+    },
+  },
+
+  "registrations:list": {
+    summary: "List an event's confirmed registrations",
+    usage: "congressio registrations list --event <eventId> [--all] [--json]",
+    needsKey: true,
+    async run({ config, flags, io }) {
+      const eventId = requireFlag(
+        flags,
+        "event",
+        "an event UUID from `my events`",
+      );
+      const path = `/api/v1/events/${encodeURIComponent(eventId)}/registrations`;
+      const { items, rateLimit } =
+        flags.all === true
+          ? await collectAll(path, config, io)
+          : await request(path, { ...config, onNotice: io.warn }).then((r) => ({
+              items: r.data.data,
+              rateLimit: r.rateLimit,
+            }));
+
+      io.quota(rateLimit);
+      if (config.json) return asJson({ data: items });
+      if (items.length === 0) return "No confirmed registrations yet.";
+      return table(items, [
+        { key: "name", label: "name" },
+        { key: "email", label: "email" },
+        { key: "tier", label: "tier" },
+        { label: "paid", value: (r) => (r.paid ? "yes" : "no") },
+      ]);
+    },
+  },
+
+  "registrations:create": {
+    summary: "Register an attendee (comped — takes no payment)",
+    usage:
+      "congressio registrations create --event <eventId> --name <name> --email <email> [--tier <tier>]",
+    needsKey: true,
+    async run({ config, flags, io }) {
+      const eventId = requireFlag(
+        flags,
+        "event",
+        "an event UUID from `my events`",
+      );
+      const body = {
+        name: requireFlag(flags, "name"),
+        email: requireFlag(flags, "email"),
+      };
+      if (flags.tier && flags.tier !== true) body.tier = String(flags.tier);
+
+      const { data, rateLimit } = await request(
+        `/api/v1/events/${encodeURIComponent(eventId)}/registrations`,
+        { ...config, method: "POST", body, onNotice: io.warn },
+      );
+      io.quota(rateLimit);
+      if (config.json) return asJson(data);
+      const r = data.data;
+      return `Registered ${r.name} <${r.email}> as #${r.registrationNumber}${
+        r.tier ? ` (${r.tier})` : ""
+      }. Pass serial ${r.passSerial ?? "—"}.`;
+    },
+  },
+
+  "docs:list": {
+    summary: "List the documentation pages",
+    usage: "congressio docs list",
+    needsKey: false,
+    async run({ config, io }) {
+      const body = await fetchMarkdown("/docs", config, io);
+      return body;
+    },
+  },
+
+  "docs:show": {
+    summary: "Print a documentation page as Markdown",
+    usage: "congressio docs show <slug>",
+    needsKey: false,
+    async run({ config, subject, io }) {
+      if (!subject) throw new UsageError("a documentation slug is required");
+      return fetchMarkdown(`/docs/${encodeURIComponent(subject)}`, config, io);
+    },
+  },
+
+  openapi: {
+    summary: "Print the OpenAPI document",
+    usage: "congressio openapi",
+    needsKey: false,
+    async run({ config, io }) {
+      const { data } = await request("/openapi.json", {
+        ...config,
+        onNotice: io.warn,
+      });
+      return asJson(data);
+    },
+  },
+};
+
+/**
+ * Fetch a page as Markdown rather than HTML.
+ *
+ * The site negotiates on `Accept`, so the CLI asks for `text/markdown` and
+ * gets the documentation as its authored source instead of scraping a rendered
+ * React page.
+ */
+async function fetchMarkdown(path, config, io) {
+  const response = await fetch(`${config.baseUrl}${path}`, {
+    headers: { Accept: "text/markdown", "User-Agent": "congressio-cli" },
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new ApiError(response.status, { message: text.split("\n")[0] }, null);
+  }
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.includes("markdown")) {
+    io.warn(
+      `warning: ${path} answered ${type || "an unknown type"}, not Markdown`,
+    );
+  }
+  return text.trimEnd();
+}
+
+/**
+ * Resolve the words before the flags to a command and its subject.
+ *
+ * Three shapes, so the obvious spelling works in each case:
+ *   `events get ecsc-2026` → events:get, subject from the positional
+ *   `docs api-webhooks`    → docs:show, subject from the subcommand slot
+ *   `openapi`              → a bare top-level command
+ */
+export function resolveCommand(command, subcommand, positionals = []) {
+  if (!command) return null;
+
+  if (subcommand && COMMANDS[`${command}:${subcommand}`]) {
+    return { key: `${command}:${subcommand}`, subject: positionals[0] ?? null };
+  }
+  if (command === "docs") {
+    return subcommand
+      ? { key: "docs:show", subject: subcommand }
+      : { key: "docs:list", subject: null };
+  }
+  if (COMMANDS[command]) {
+    return { key: command, subject: subcommand ?? null };
+  }
+  return null;
+}

package/lib/format.mjs

@@ -0,0 +1,73 @@
+/**
+ * Output formatting for the Congressio CLI.
+ *
+ * Two modes, and the distinction matters for the tool's main audience:
+ *   - default: a column-aligned table for a person reading a terminal;
+ *   - `--json`: the API payload, verbatim and unreshaped, for a script or an
+ *     agent to parse. Never pretty, never truncated, never annotated — if the
+ *     CLI reshaped it, a caller could not rely on the OpenAPI schema.
+ *
+ * Progress and warnings always go to stderr, so `--json` stdout stays a single
+ * valid JSON document that can be piped straight into `jq`.
+ */
+
+/** Visible width, ignoring the escape sequences we might have added. */
+function width(value) {
+  return String(value).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/**
+ * Render rows as an aligned table.
+ *
+ * `columns` is `[{ key, label, value? }]`; `value` maps a row to its cell so a
+ * nested field can be flattened without mutating the API payload.
+ */
+export function table(rows, columns) {
+  if (rows.length === 0) return "";
+
+  const cells = rows.map((row) =>
+    columns.map((column) => {
+      const raw = column.value ? column.value(row) : row[column.key];
+      if (raw === null || raw === undefined || raw === "") return "—";
+      return String(raw);
+    }),
+  );
+
+  const widths = columns.map((column, i) =>
+    Math.max(width(column.label), ...cells.map((row) => width(row[i]))),
+  );
+
+  const pad = (value, i) =>
+    value + " ".repeat(Math.max(0, widths[i] - width(value)));
+
+  const lines = [
+    columns.map((c, i) => pad(c.label.toUpperCase(), i)).join("  "),
+    widths.map((w) => "─".repeat(w)).join("  "),
+    ...cells.map((row) => row.map(pad).join("  ")),
+  ];
+  return lines.join("\n").replace(/ +$/gm, "");
+}
+
+/** `2026-09-14 → 2026-09-17`, or a single date, or an em dash. */
+export function dateRange(start, end) {
+  const day = (value) => (value ? String(value).slice(0, 10) : null);
+  const a = day(start);
+  const b = day(end);
+  if (a && b) return a === b ? a : `${a} → ${b}`;
+  return a ?? b ?? "—";
+}
+
+/** One-line quota summary for stderr, or null when the API reported none. */
+export function quotaLine(rateLimit) {
+  if (!rateLimit || rateLimit.remaining === null) return null;
+  const reset =
+    rateLimit.resetSeconds === null
+      ? ""
+      : `, resets in ${rateLimit.resetSeconds}s`;
+  return `${rateLimit.remaining}/${rateLimit.limit ?? "?"} requests left${reset}`;
+}
+
+/** The API payload, unreshaped, as a single JSON document. */
+export function asJson(payload) {
+  return JSON.stringify(payload, null, 2);
+}

package/lib/help.mjs

@@ -0,0 +1,66 @@
+import { COMMANDS } from "./commands.mjs";
+
+/**
+ * `--help` output.
+ *
+ * Written to be useful to an agent reading it once: every command with its
+ * exact usage line, whether it needs a key, and how to supply one. No colour,
+ * no boxes — the text has to survive being pasted into a model's context.
+ */
+export function helpText(version) {
+  const rows = Object.entries(COMMANDS).map(([key, command]) => ({
+    // `events:list` → `events list`. Keeping the name column narrow leaves the
+    // summaries readable; the full argument lists go in their own block below.
+    name: key.replace(":", " "),
+    usage: command.usage.replace(/^congressio /, ""),
+    needsKey: command.needsKey,
+    summary: command.summary,
+  }));
+
+  const width = Math.max(...rows.map((r) => r.name.length));
+  const lines = [
+    `congressio ${version} — command-line access to the Congressio conference platform`,
+    "",
+    "USAGE",
+    "  congressio <command> [options]",
+    "",
+    "COMMANDS",
+    ...rows.map(
+      (r) =>
+        `  ${r.name.padEnd(width)}  ${r.summary}${r.needsKey ? " [key]" : ""}`,
+    ),
+    "",
+    "ARGUMENTS",
+    ...rows.map((r) => `  ${r.usage}`),
+    "",
+    "OPTIONS",
+    "  --json              Print the API response verbatim, for scripts and agents",
+    "  --all               Follow pagination and return every item",
+    "  --retry             On a 429, wait Retry-After and try again",
+    "  --api-key <key>     Override CONGRESSIO_API_KEY",
+    "  --base-url <url>    Point at another deployment (default https://congressio.net)",
+    "  --quiet             Suppress progress and quota notes on stderr",
+    "  -h, --help          Show this help",
+    "  -v, --version       Show the version",
+    "",
+    "AUTHENTICATION",
+    "  Commands marked [key] need an organization API key. Create one in",
+    "  Congressio under Organization settings → API, then export it:",
+    "",
+    "    export CONGRESSIO_API_KEY=cong_live_…",
+    "",
+    "  Commands without [key] need no credentials at all.",
+    "",
+    "NOTES",
+    "  Output: --json writes the API payload unchanged to stdout; progress,",
+    "  warnings and rate-limit notes always go to stderr, so `--json` output",
+    "  pipes cleanly into jq.",
+    "  Exit codes: 0 success, 1 API error, 2 usage error.",
+    "",
+    "DOCUMENTATION",
+    "  https://congressio.net/developers    API reference and scopes",
+    "  https://congressio.net/openapi.json  OpenAPI 3.1 description",
+    "  https://congressio.net/llms.txt      Guidance for AI agents",
+  ];
+  return lines.join("\n");
+}

package/lib/http.mjs

@@ -0,0 +1,156 @@
+/**
+ * HTTP layer for the Congressio CLI: one request helper that understands the
+ * API's error envelope and its rate-limit headers.
+ *
+ * Built on global `fetch` (Node 20+), so there is no HTTP dependency to ship.
+ */
+
+/** Thrown for any non-2xx response, carrying the parsed error envelope. */
+export class ApiError extends Error {
+  constructor(status, body, retryAfterSeconds) {
+    const message = (body && (body.message || body.error)) || `HTTP ${status}`;
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    /** Stable machine-readable code from the API (`not_found`, `forbidden`, …). */
+    this.code = (body && body.code) || null;
+    /** What the API says to do about it — worth printing verbatim. */
+    this.hint = (body && body.hint) || null;
+    this.docs = (body && body.docs) || null;
+    this.retryAfterSeconds = retryAfterSeconds ?? null;
+  }
+}
+
+/**
+ * Read the quota state the API publishes.
+ *
+ * Prefers the structured `RateLimit` field and falls back to the dashed
+ * triple, so the CLI keeps working whichever spelling the server emits.
+ * Returns nulls rather than guesses when a field is absent — the API omits
+ * live state when its counter is unknown, and inventing a number here would
+ * defeat the point.
+ */
+export function readRateLimit(headers) {
+  const structured = headers.get("ratelimit");
+  if (structured) {
+    const remaining = structured.match(/[;\s]r=(\d+)/);
+    const reset = structured.match(/[;\s]t=(\d+)/);
+    const policy = headers.get("ratelimit-policy") ?? "";
+    const limit = policy.match(/[;\s]q=(\d+)/);
+    return {
+      limit: limit ? Number(limit[1]) : null,
+      remaining: remaining ? Number(remaining[1]) : null,
+      resetSeconds: reset ? Number(reset[1]) : null,
+    };
+  }
+
+  const num = (name) => {
+    const raw = headers.get(name);
+    return raw === null || raw === "" ? null : Number(raw);
+  };
+  return {
+    limit: num("ratelimit-limit"),
+    remaining: num("ratelimit-remaining"),
+    resetSeconds: num("ratelimit-reset"),
+  };
+}
+
+/** `Sunset` / `Deprecation`, so a scripted caller is warned before a break. */
+export function readDeprecation(headers) {
+  const deprecation = headers.get("deprecation");
+  const sunset = headers.get("sunset");
+  if (!deprecation && !sunset) return null;
+  return { deprecation, sunset };
+}
+
+/** Seconds to wait, from `Retry-After`. */
+function retryAfter(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return seconds;
+  // RFC 9110 permits an HTTP-date instead of a delta.
+  const at = Date.parse(raw);
+  return Number.isNaN(at)
+    ? null
+    : Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
+
+const sleep = (seconds) =>
+  new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+
+/**
+ * Perform one API request.
+ *
+ * With `retry`, a 429 is honoured exactly as instructed — wait `Retry-After`,
+ * then try again, at most `maxRetries` times. That is the whole reason the
+ * server publishes the header, and it keeps an agent from hammering a limit
+ * it has already been told about.
+ */
+export async function request(
+  path,
+  {
+    baseUrl,
+    apiKey,
+    method = "GET",
+    body,
+    retry = false,
+    maxRetries = 3,
+    fetchImpl = fetch,
+    onNotice = () => {},
+  },
+) {
+  const url = `${baseUrl}${path}`;
+  const headers = {
+    Accept: "application/json",
+    "User-Agent": "congressio-cli",
+  };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+
+  for (let attempt = 0; ; attempt++) {
+    const response = await fetchImpl(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+
+    const deprecated = readDeprecation(response.headers);
+    if (deprecated) {
+      onNotice(
+        `warning: ${method} ${path} is deprecated` +
+          (deprecated.sunset
+            ? ` and stops responding after ${deprecated.sunset}`
+            : ""),
+      );
+    }
+
+    let payload = null;
+    const text = await response.text();
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = null;
+      }
+    }
+
+    if (response.ok) {
+      return { data: payload, rateLimit: readRateLimit(response.headers) };
+    }
+
+    const wait = retryAfter(response.headers);
+    if (
+      response.status === 429 &&
+      retry &&
+      attempt < maxRetries &&
+      wait !== null
+    ) {
+      onNotice(`rate limited; waiting ${wait}s as instructed by Retry-After`);
+      await sleep(wait);
+      continue;
+    }
+
+    throw new ApiError(response.status, payload, wait);
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@congressio/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Command-line access to the Congressio conference management platform: public conference directory, submissions, peer review and attendee registrations.",
+  "keywords": [
+    "congressio",
+    "cli",
+    "conference",
+    "call-for-papers",
+    "peer-review",
+    "abstracts",
+    "registration",
+    "api"
+  ],
+  "homepage": "https://congressio.net/cli",
+  "bugs": {
+    "url": "https://congressio.net/contact"
+  },
+  "license": "MIT",
+  "author": "RivTech SAS",
+  "type": "module",
+  "bin": {
+    "congressio": "bin/congressio.mjs"
+  },
+  "exports": {
+    ".": "./lib/commands.mjs",
+    "./http": "./lib/http.mjs",
+    "./format": "./lib/format.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "congressio": "node bin/congressio.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}