@localpulse/cli 0.0.1 → 0.0.2

package/README.md

@@ -25,8 +25,17 @@ chmod +x localpulse
 # Authenticate
 localpulse auth login --token lp_cli_...
 
-# Search events
-localpulse search "techno amsterdam" --date weekend --tz Europe/Amsterdam
+# Search upcoming events
+localpulse search "techno amsterdam"
+
+# Search with filters
+localpulse search "festival" --date weekend --tz Europe/Amsterdam
+
+# Include past events
+localpulse search "amsterdam" --all
+
+# Structured JSON output
+localpulse search "berlin" --json
 
 # Ingest a poster (creates a draft for review)
 localpulse ingest poster.jpg --research metadata.json
@@ -47,11 +56,13 @@ Remove stored credentials.
 
 ### `ingest <file> --research <payload.json>`
 
-Upload an event poster with research metadata. By default creates a draft for review at `localpulse.nl/publish/edit/<id>`. Use `--force` to submit directly. Use `--generate-skeleton` to see the research JSON format.
+Upload an event poster with research metadata. By default creates a draft for review at `localpulse.nl/publish/edit/<id>`. Use `--force` to submit directly. Use `--generate-skeleton` to see the research JSON format. Pass `--json` for structured output.
 
 ### `search <query>`
 
-Search events by text. Supports `--city`, `--date today|weekend`, `--tz`, `--limit`, `--cursor`.
+Search upcoming events by default. Supports `--city`, `--date today|weekend|upcoming`, `--tz`, `--all` (include past), `--json`, `--limit`, `--cursor`.
+
+All commands support `--json` for structured, machine-parseable output.
 
 ## Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localpulse/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Local Pulse CLI — ingest event posters, search events, manage credentials",
   "type": "module",
   "license": "MIT",

package/src/index.test.ts

@@ -24,12 +24,14 @@ function runCli(...args: string[]): { exitCode: number; stdout: string; stderr:
 }
 
 describe("localpulse", () => {
-  it("shows root help with expected commands", () => {
+  it("shows root help with expected commands and quick start", () => {
     const { exitCode, stdout } = runCli("--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("ingest");
     expect(stdout).toContain("search");
     expect(stdout).toContain("auth");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Quick start:");
     expect(stdout).not.toMatch(/^\s+directives\s/m);
     expect(stdout).not.toMatch(/^\s+event\s/m);
     expect(stdout).not.toMatch(/^\s+status\s/m);
@@ -43,12 +45,14 @@ describe("localpulse", () => {
     expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
   });
 
-  it("shows ingest help with research as primary input", () => {
+  it("shows ingest help with research, --json, and examples", () => {
     const { exitCode, stdout } = runCli("ingest", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--research");
     expect(stdout).toContain("--generate-skeleton");
     expect(stdout).toContain("--dry-run");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
     expect(stdout).not.toContain("--performers");
     expect(stdout).not.toContain("--genre");
     expect(stdout).not.toContain("--socials");
@@ -57,26 +61,41 @@ describe("localpulse", () => {
     expect(stdout).not.toContain("--batch");
   });
 
-  it("shows search help with --date instead of --time", () => {
+  it("shows search help with --date, --all, --json, and examples", () => {
     const { exitCode, stdout } = runCli("search", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--date");
     expect(stdout).toContain("--city");
+    expect(stdout).toContain("--all");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("upcoming");
+    expect(stdout).toContain("Examples:");
     expect(stdout).not.toContain("--time");
   });
 
-  it("shows auth help", () => {
+  it("shows auth help with examples", () => {
     const { exitCode, stdout } = runCli("auth", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("login");
     expect(stdout).toContain("logout");
+    expect(stdout).toContain("Examples:");
   });
 
-  it("shows auth login help", () => {
+  it("shows drafts help with --status, --json, and examples", () => {
+    const { exitCode, stdout } = runCli("drafts", "--help");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--status");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
+  });
+
+  it("shows auth login help with examples", () => {
     const { exitCode, stdout } = runCli("auth", "login", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--token");
     expect(stdout).toContain("--api-url");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
   });
 
   it("rejects unknown commands", () => {

package/src/index.ts

@@ -4,8 +4,10 @@ import { stdin, stdout } from "node:process";
 
 import { hasOption, parseArgv, readNumberOption, readStringArrayOption, readStringOption } from "./lib/argv";
 import { requireToken } from "./lib/auth";
-import { searchCliEvents } from "./lib/cli-read-client";
-import type { SearchEventCard } from "./lib/cli-read-types";
+import { toFrontendBaseUrl } from "./lib/api-url";
+import { fetchDrafts, searchCliEvents } from "./lib/cli-read-client";
+import { DRAFT_STATUSES } from "./lib/cli-read-types";
+import type { DraftListItem, DraftStatus, SearchEventCard } from "./lib/cli-read-types";
 import {
   deleteCredentials,
   getCredentialsPath,
@@ -60,6 +62,9 @@ async function main(argv: string[]): Promise<void> {
       case "search":
         await runSearch(parsed);
         break;
+      case "drafts":
+        await runDrafts(parsed);
+        break;
       default:
         throw new Error(`Unknown command: ${command}. Run \`localpulse --help\` for usage.`);
     }
@@ -83,7 +88,7 @@ async function runAuth(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   if (subcommand === "login") {
     await runAuthLogin(parsed);
   } else {
-    await runAuthLogout();
+    await runAuthLogout(parsed);
   }
 }
 
@@ -93,6 +98,7 @@ async function runAuthLogin(parsed: ReturnType<typeof parseArgv>): Promise<void>
     return;
   }
 
+  const jsonOutput = hasOption(parsed, "json");
   const apiUrl = readStringOption(parsed, "api-url")?.trim() || getDefaultApiUrl();
   const token = await resolveLoginToken(readStringOption(parsed, "token"));
   if (!isLikelyCliToken(token)) {
@@ -100,12 +106,19 @@ async function runAuthLogin(parsed: ReturnType<typeof parseArgv>): Promise<void>
   }
 
   const result = await loginWithToken(apiUrl, token);
-  stdout.write(`Authenticated. Credentials saved to ${result.credentials_path}\n`);
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ authenticated: true, credentials_path: result.credentials_path })}\n`);
+  } else {
+    stdout.write(`Authenticated. Credentials saved to ${result.credentials_path}\n`);
+  }
 }
 
-async function runAuthLogout(): Promise<void> {
+async function runAuthLogout(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  const jsonOutput = hasOption(parsed, "json");
   const deleted = await deleteCredentials();
-  if (deleted) {
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ logged_out: deleted })}\n`);
+  } else if (deleted) {
     stdout.write("Logged out. Credentials removed.\n");
   } else {
     stdout.write("No credentials found.\n");
@@ -143,6 +156,7 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   const apiUrl = await resolveApiUrl();
   const dryRun = hasOption(parsed, "dry-run");
   const force = hasOption(parsed, "force");
+  const jsonOutput = hasOption(parsed, "json");
   const token = dryRun ? "" : await requireToken();
 
   const uploadOptions = {
@@ -157,13 +171,16 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
     venue: readStringOption(parsed, "venue") ?? mapped.venue,
     extraMedia: readStringArrayOption(parsed, "extra-media"),
     dryRun,
-    force,
   };
 
   if (dryRun) {
     const result = await uploadPoster(apiUrl, token, uploadOptions);
     if ("dry_run" in result) {
-      stdout.write(`Dry run passed: ${result.file} (${result.extra_media_count} extra media)\n`);
+      if (jsonOutput) {
+        stdout.write(`${JSON.stringify(result)}\n`);
+      } else {
+        stdout.write(`Dry run passed: ${result.file} (${result.extra_media_count} extra media)\n`);
+      }
     }
     return;
   }
@@ -171,25 +188,39 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   if (force) {
     const result = await uploadPoster(apiUrl, token, uploadOptions);
     if (!("dry_run" in result)) {
-      printIngestResult(result);
+      if (jsonOutput) {
+        stdout.write(`${JSON.stringify(result)}\n`);
+      } else {
+        printIngestResult(result);
+      }
     }
     return;
   }
 
   // Default: draft flow
   const draft = await runDraftIngest(apiUrl, token, file, uploadOptions);
-  printDraftResult(draft, apiUrl);
+  if (jsonOutput) {
+    const baseUrl = toFrontendBaseUrl(apiUrl);
+    stdout.write(`${JSON.stringify({ draft_id: draft.id, status: draft.status, edit_url: `${baseUrl}/publish/edit/${draft.id}` })}\n`);
+  } else {
+    printDraftResult(draft, apiUrl);
+  }
 }
 
 async function validateFilePaths(primaryFile: string, extraMedia?: string[]): Promise<void> {
-  const { existsSync } = await import("node:fs");
-  const missing: string[] = [];
-  if (!existsSync(primaryFile)) missing.push(primaryFile);
-  for (const p of extraMedia ?? []) {
-    if (!existsSync(p)) missing.push(p);
+  const { access } = await import("node:fs/promises");
+
+  if (extraMedia && extraMedia.length > 2) {
+    throw new Error("`--extra-media` supports at most 2 files.");
   }
-  if (missing.length) {
-    throw new Error(`File(s) not found: ${missing.join(", ")}`);
+
+  const checkFile = async (path: string, label: string) => {
+    try { await access(path); } catch { throw new Error(`File not found: ${path} (${label})`); }
+  };
+
+  await checkFile(primaryFile, "file");
+  for (const [i, p] of (extraMedia ?? []).entries()) {
+    await checkFile(p, `extra-media[${i}]`);
   }
 }
 
@@ -201,11 +232,11 @@ async function runDraftIngest(
 ): Promise<DraftResult> {
   await validateFilePaths(primaryFile, options.extraMedia);
 
-  stdout.write("Creating draft...\n");
+  process.stderr.write("Creating draft...\n");
   const draft = await createDraft(apiUrl, token, options);
 
-  stdout.write(`Draft created: ${draft.id}\n`);
-  stdout.write("Uploading primary media...\n");
+  process.stderr.write(`Draft created: ${draft.id}\n`);
+  process.stderr.write("Uploading primary media...\n");
   await uploadDraftMedia(apiUrl, token, draft.id, primaryFile, {
     mediaType: detectMediaType(primaryFile),
     sortOrder: 0,
@@ -214,7 +245,7 @@ async function runDraftIngest(
 
   if (options.extraMedia?.length) {
     for (const [index, path] of options.extraMedia.entries()) {
-      stdout.write(`Uploading extra media ${index + 1}...\n`);
+      process.stderr.write(`Uploading extra media ${index + 1}...\n`);
       await uploadDraftMedia(apiUrl, token, draft.id, path, {
         mediaType: detectMediaType(path),
         sortOrder: index + 1,
@@ -227,7 +258,7 @@ async function runDraftIngest(
 }
 
 function printDraftResult(draft: DraftResult, apiUrl: string): void {
-  const baseUrl = apiUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+  const baseUrl = toFrontendBaseUrl(apiUrl);
   stdout.write(`\nDraft saved: ${draft.id}\n`);
   stdout.write("Open the publish dashboard to review and submit:\n");
   stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
@@ -254,19 +285,29 @@ async function runSearch(parsed: ReturnType<typeof parseArgv>): Promise<void> {
 
   const query = parsed.positionals.join(" ").trim();
   if (!query) {
-    throw new Error("Search query is required. Run `localpulse search --help` for usage.");
+    throw new Error("Search query is required.\n  localpulse search \"amsterdam\"\n  localpulse search --help");
   }
 
+  const jsonOutput = hasOption(parsed, "json");
+  const allEvents = hasOption(parsed, "all");
+  const dateFilter = readDateFilterOption(parsed);
+  const time_intent = allEvents ? undefined : (dateFilter ?? "upcoming");
+
   const apiUrl = await resolveApiUrl();
   const result = await searchCliEvents(apiUrl, {
     query,
     city: readStringOption(parsed, "city"),
-    time_intent: readDateFilterOption(parsed),
+    time_intent,
     timezone: readStringOption(parsed, "tz"),
     limit: readNumberOption(parsed, "limit") ?? 10,
     cursor: readNumberOption(parsed, "cursor") ?? 0,
   });
 
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
   if (result.results.length === 0) {
     stdout.write("No events found.\n");
     return;
@@ -295,6 +336,63 @@ function printSearchCard(card: SearchEventCard): void {
   stdout.write(`  ${card.frontend_url}\n`);
 }
 
+const VALID_DRAFT_STATUSES: ReadonlySet<string> = new Set<DraftStatus>(DRAFT_STATUSES);
+
+function countByStatus(drafts: DraftListItem[]): Record<DraftStatus, number> {
+  const counts: Record<DraftStatus, number> = { uploading: 0, processing: 0, ready: 0, failed: 0 };
+  for (const d of drafts) counts[d.status]++;
+  return counts;
+}
+
+async function runDrafts(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help")) {
+    stdout.write(draftsHelp());
+    return;
+  }
+
+  const jsonOutput = hasOption(parsed, "json");
+  const statusFilter = readStringOption(parsed, "status");
+
+  if (statusFilter && !VALID_DRAFT_STATUSES.has(statusFilter)) {
+    throw new Error(
+      `\`--status\` must be \`uploading\`, \`processing\`, \`ready\`, or \`failed\`.\n  localpulse drafts --status failed`,
+    );
+  }
+
+  const apiUrl = await resolveApiUrl();
+  const token = await requireToken();
+  const drafts = await fetchDrafts(apiUrl, token, statusFilter as DraftStatus | undefined);
+  const counts = countByStatus(drafts);
+
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ total: drafts.length, counts, drafts }, null, 2)}\n`);
+    return;
+  }
+
+  if (drafts.length === 0) {
+    stdout.write("No drafts.\n");
+    return;
+  }
+
+  const summary = Object.entries(counts).filter(([, n]) => n > 0).map(([s, n]) => `${n} ${s}`).join(", ");
+  stdout.write(`Drafts: ${drafts.length} total (${summary})\n\n`);
+
+  const baseUrl = toFrontendBaseUrl(apiUrl);
+  for (const draft of drafts) {
+    printDraftListItem(draft, baseUrl);
+  }
+}
+
+function printDraftListItem(draft: DraftListItem, baseUrl: string): void {
+  const title = draft.metadata?.event_title ? `"${draft.metadata.event_title}"` : "";
+  const status = draft.status.padEnd(10);
+  stdout.write(`${draft.id}  ${status}  ${draft.updated_at}  ${title}\n`);
+  if (draft.status === "failed" && draft.error_message) {
+    stdout.write(`  Error: ${draft.error_message}\n`);
+  }
+  stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
+}
+
 async function resolveLoginToken(explicitToken?: string): Promise<string> {
   if (explicitToken?.trim()) {
     return explicitToken.trim();
@@ -321,15 +419,15 @@ async function resolveLoginToken(explicitToken?: string): Promise<string> {
 
 function readDateFilterOption(
   parsed: ReturnType<typeof parseArgv>,
-): "today" | "weekend" | undefined {
+): "today" | "weekend" | "upcoming" | undefined {
   const value = readStringOption(parsed, "date");
   if (!value) {
     return undefined;
   }
-  if (value === "today" || value === "weekend") {
+  if (value === "today" || value === "weekend" || value === "upcoming") {
     return value;
   }
-  throw new Error("`--date` must be `today` or `weekend`.");
+  throw new Error("`--date` must be `today`, `weekend`, or `upcoming`.\n  localpulse search \"amsterdam\" --date today --tz Europe/Amsterdam");
 }
 
 function rootHelp(): string {
@@ -337,16 +435,23 @@ function rootHelp(): string {
 
 Commands:
   ingest   Ingest an event poster into Local Pulse
-  search   Search existing events
+  search   Search upcoming events
+  drafts   List your submission drafts
   auth     Login and logout
 
 Options:
   --help     Show help
   --version  Show version
+  --json     Output structured JSON (supported by all commands)
 
 Environment:
   LP_TOKEN    Override stored auth token
   LP_API_URL  Override API base URL (default: https://localpulse.nl)
+
+Quick start:
+  localpulse auth login --token <token>
+  localpulse search "amsterdam"
+  localpulse ingest poster.jpg --research data.json
 `;
 }
 
@@ -357,7 +462,10 @@ Commands:
   login    Authenticate with a Local Pulse CLI token
   logout   Remove stored credentials
 
-Run \`localpulse auth login --help\` for login options.
+Examples:
+  localpulse auth login --token lp_cli_...
+  LP_TOKEN=lp_cli_... localpulse auth login
+  localpulse auth logout
 `;
 }
 
@@ -367,9 +475,15 @@ function authLoginHelp(): string {
 Options:
   --token <token>        Local Pulse CLI token
   --api-url <url>        Override API base URL
+  --json                 Output structured JSON
   --help                 Show this help
 
 Without --token, prompts interactively (visit https://localpulse.nl/dev to create a token).
+
+Examples:
+  localpulse auth login --token lp_cli_...
+  localpulse auth login --token lp_cli_... --json
+  LP_TOKEN=lp_cli_... localpulse auth login
 `;
 }
 
@@ -441,29 +555,60 @@ Extra:
   --extra-media <file>... Up to 2 additional poster or flyer images
 
 Options:
+  --json                  Output structured JSON
   --help                  Show this help
 
-Example:
+Examples:
   localpulse ingest --generate-skeleton > research.json
-  # research and fill in the payload
-  localpulse ingest ./poster.jpg --research research.json
+  localpulse ingest poster.jpg --research research.json
+  localpulse ingest poster.jpg --research research.json --force
+  localpulse ingest poster.jpg --research research.json --json
+  cat research.json | localpulse ingest poster.jpg --research -
 `;
 }
 
 function searchHelp(): string {
   return `Usage: localpulse search <query> [options]
 
-Search existing events on Local Pulse.
+Search events on Local Pulse. Returns upcoming events by default.
 
 Arguments:
   query                 Free-text search query
 
 Options:
   --city <text>         Filter by city
-  --date <today|weekend> Time intent filter
+  --date <today|weekend|upcoming>  Time intent filter (default: upcoming)
   --tz <timezone>       IANA timezone (requires --date)
+  --all                 Include past events
+  --json                Output structured JSON
   --limit <n>           Results per page (1-25, default 10)
   --cursor <n>          Pagination offset
   --help                Show this help
+
+Examples:
+  localpulse search "amsterdam"
+  localpulse search "techno" --city Amsterdam
+  localpulse search "festival" --date weekend --tz Europe/Amsterdam
+  localpulse search "amsterdam" --all
+  localpulse search "berlin" --json
+  localpulse search "amsterdam" --json | jq '.results[].frontend_url'
+`;
+}
+
+function draftsHelp(): string {
+  return `Usage: localpulse drafts [options]
+
+List your event submission drafts and their status.
+
+Options:
+  --status <uploading|processing|ready|failed>  Filter by status
+  --json                Output structured JSON
+  --help                Show this help
+
+Examples:
+  localpulse drafts
+  localpulse drafts --status failed
+  localpulse drafts --json
+  localpulse drafts --json | jq '.counts'
 `;
 }

package/src/lib/api-url.ts

@@ -13,3 +13,7 @@ export function buildApiUrl(apiUrl: string, path: string): string {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
   return `${normalizeApiUrl(apiUrl)}${normalizedPath}`;
 }
+
+export function toFrontendBaseUrl(apiUrl: string): string {
+  return apiUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+}

package/src/lib/cli-read-client.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, mock } from "bun:test";
 import { CliApiError } from "./api-response";
 import {
   fetchCliInfo,
+  fetchDrafts,
   searchCliEvents,
 } from "./cli-read-client";
 
@@ -70,6 +71,53 @@ describe("cli-read-client", () => {
     });
   });
 
+  it("encodes upcoming time_intent in query params", async () => {
+    globalThis.fetch = mock(async (input) => {
+      expect(String(input)).toBe(
+        "https://localpulse.nl/api/cli/events/search?query=berlin&limit=10&cursor=0&time_intent=upcoming",
+      );
+      return new Response(
+        JSON.stringify({ results: [], cursor: 0, next_cursor: null }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    expect(
+      await searchCliEvents("https://localpulse.nl", {
+        query: "berlin",
+        time_intent: "upcoming",
+        limit: 10,
+        cursor: 0,
+      }),
+    ).toEqual({ results: [], cursor: 0, next_cursor: null });
+  });
+
+  it("fetches drafts with auth header", async () => {
+    globalThis.fetch = mock(async (input, init) => {
+      expect(String(input)).toBe("https://localpulse.nl/api/drafts");
+      expect(init?.headers).toMatchObject({ authorization: "Bearer test-token" });
+      return new Response(
+        JSON.stringify([
+          { id: "abc", status: "uploading", error_message: null, metadata: null, created_at: "2026-01-01T00:00:00Z", updated_at: "2026-01-01T00:00:00Z" },
+        ]),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const result = await fetchDrafts("https://localpulse.nl", "test-token");
+    expect(result).toHaveLength(1);
+    expect(result[0].status).toBe("uploading");
+  });
+
+  it("passes status filter to drafts endpoint", async () => {
+    globalThis.fetch = mock(async (input) => {
+      expect(String(input)).toBe("https://localpulse.nl/api/drafts?status=failed");
+      return new Response(JSON.stringify([]), { status: 200, headers: { "Content-Type": "application/json" } });
+    }) as typeof fetch;
+
+    expect(await fetchDrafts("https://localpulse.nl", "test-token", "failed")).toEqual([]);
+  });
+
   it("surfaces REST error responses", async () => {
     globalThis.fetch = mock(async () => {
       return new Response(

package/src/lib/cli-read-client.ts

@@ -7,6 +7,8 @@ import {
 import { buildApiUrl } from "./api-url";
 import type {
   CliInfoResult,
+  DraftListItem,
+  DraftStatus,
   SearchEventsResult,
 } from "./cli-read-types";
 
@@ -20,7 +22,7 @@ export async function searchCliEvents(
   args: {
     query: string;
     city?: string;
-    time_intent?: "today" | "weekend";
+    time_intent?: "today" | "weekend" | "upcoming";
     timezone?: string;
     limit: number;
     cursor: number;
@@ -84,6 +86,42 @@ function parseCliInfoResult(payload: ApiResponseBody): CliInfoResult {
   return result as CliInfoResult;
 }
 
+export async function fetchDrafts(
+  apiUrl: string,
+  token: string,
+  status?: DraftStatus,
+): Promise<DraftListItem[]> {
+  const path = status ? `/api/drafts?status=${encodeURIComponent(status)}` : "/api/drafts";
+  const response = await fetch(buildApiUrl(apiUrl, path), {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${token}`,
+    },
+  });
+
+  const text = await response.text();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new CliApiError("Drafts fetch returned non-JSON response", { httpStatus: response.status });
+  }
+
+  if (!response.ok) {
+    const body = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as ApiResponseBody : undefined;
+    throw new CliApiError(extractApiErrorMessage(body ?? {}, `Drafts fetch failed (${response.status})`), {
+      httpStatus: response.status,
+      body,
+    });
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("Invalid API response: expected drafts array.");
+  }
+  return parsed as DraftListItem[];
+}
+
 function parseSearchEventsResult(payload: ApiResponseBody): SearchEventsResult {
   const result = payload as Partial<SearchEventsResult>;
   if (

package/src/lib/cli-read-types.ts

@@ -25,3 +25,15 @@ export type SearchEventsResult = {
   cursor: number;
   next_cursor: number | null;
 };
+
+export const DRAFT_STATUSES = ["uploading", "processing", "ready", "failed"] as const;
+export type DraftStatus = (typeof DRAFT_STATUSES)[number];
+
+export type DraftListItem = {
+  id: string;
+  status: DraftStatus;
+  error_message: string | null;
+  metadata: { event_title?: string; venue_name?: string; poster_id?: string } | null;
+  created_at: string;
+  updated_at: string;
+};

package/src/lib/upload-client.ts

@@ -23,8 +23,6 @@ export type IngestUploadOptions = {
   venue?: string;
   extraMedia?: string[];
   dryRun?: boolean;
-  /** When true, bypass drafts and upload directly to the ingestion pipeline. */
-  force?: boolean;
 };
 
 export type UploadDryRunResult = {