@verbatims/cli 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @verbatims/cli
+
+CLI for the [Verbatims](https://verbatims.cc) quotes API.
+
+## Install
+
+```bash
+npm install -g @verbatims/cli
+# or use directly
+npx @verbatims/cli --help
+```
+
+## Usage
+
+```bash
+# Configure API key
+verbatims config
+
+# List quotes
+verbatims quotes list --language fr --limit 10
+
+# Browse interactively
+verbatims quotes browse
+
+# Search
+verbatims search "love" --type quotes
+
+# See all commands
+verbatims --help
+```

package/bin/verbatims.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+await import('tsx')
+await import('../src/index.ts')

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@verbatims/cli",
+  "version": "0.1.0",
+  "description": "CLI for the Verbatims quotes API",
+  "type": "module",
+  "bin": {
+    "verbatims": "./bin/verbatims.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@verbatims/sdk": "^1.0.0",
+    "@clack/prompts": "^0.10.1",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "tsx": "^4.19.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rootasjey/verbatims-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/commands/authors.ts

@@ -0,0 +1,95 @@
+import type { Command } from 'commander'
+import { text, isCancel, cancel } from '@clack/prompts'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+import { browse } from '../utils/browse.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'table') as Format
+}
+
+export function registerAuthorsCommand(program: Command) {
+  const authors = program.command('authors').description('Manage authors')
+
+  authors
+    .command('list')
+    .description('List authors')
+    .option('--search <q>', 'Search authors')
+    .option('--limit <n>', 'Number of results', '20')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data, pagination } = await withSpinner('Fetching authors', () =>
+        client.authors.list({ search: options.search, limit: Number(options.limit) }),
+        format,
+      )
+      output(data, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  authors
+    .command('get <id>')
+    .description('Get an author by ID')
+    .action(async (id: string) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching author', () => client.authors.get(Number(id)), format)
+      output(data, format)
+    })
+
+  authors
+    .command('create')
+    .description('Create an author')
+    .option('--name <name>', 'Author name')
+    .option('--job <job>', 'Job title')
+    .option('--description <text>', 'Description')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const name = options.name ?? await text({ message: 'Author name', validate: (v) => !v ? 'Required' : undefined })
+      if (isCancel(name)) cancel('Cancelled')
+
+      const { data } = await withSpinner('Creating author', () =>
+        client.authors.create({ name: name as string, job: options.job ?? null, description: options.description ?? null }),
+        format,
+      )
+      console.log(chalk.green(' Author created'))
+      output(data, format)
+    })
+
+  authors
+    .command('update <id>')
+    .description('Update an author')
+    .option('--name <name>', 'Author name')
+    .option('--description <text>', 'Description')
+    .action(async (id: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const data_: Record<string, unknown> = {}
+      if (options.name) data_.name = options.name
+      if (options.description !== undefined) data_.description = options.description
+
+      const { data } = await withSpinner('Updating author', () => client.authors.update(Number(id), data_ as any), format)
+      console.log(chalk.green(' Author updated'))
+      output(data, format)
+    })
+
+  authors
+    .command('browse')
+    .description('Browse authors interactively')
+    .option('--search <q>', 'Search authors')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      await browse(
+        (page) => client.authors.list({ page, search: options.search }),
+        format,
+      )
+    })
+}

package/src/commands/collections.ts

@@ -0,0 +1,53 @@
+import type { Command } from 'commander'
+import { text, isCancel, cancel } from '@clack/prompts'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'plain') as Format
+}
+
+export function registerCollectionsCommand(program: Command) {
+  const collections = program.command('collections').description('Manage collections')
+
+  collections
+    .command('create')
+    .description('Create a collection')
+    .option('--name <name>', 'Collection name')
+    .option('--description <text>', 'Description')
+    .option('--public', 'Make collection public')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const name = options.name ?? await text({ message: 'Collection name', validate: (v) => !v ? 'Required' : undefined })
+      if (isCancel(name)) cancel('Cancelled')
+
+      const { data } = await withSpinner('Creating collection', () =>
+        client.collections.create({ name: name as string, description: options.description ?? null, is_public: Boolean(options.public) }),
+        format,
+      )
+      console.log(chalk.green(' Collection created'))
+      output(data, format)
+    })
+
+  collections
+    .command('add <collection-id> <quote-id>')
+    .description('Add a quote to a collection')
+    .action(async (collectionId: string, quoteId: string) => {
+      const client = await getClient()
+      await withSpinner('Adding quote to collection', () => client.collections.addQuote(Number(collectionId), Number(quoteId)))
+      console.log(chalk.green(` Quote #${quoteId} added to collection #${collectionId}`))
+    })
+
+  collections
+    .command('remove <collection-id> <quote-id>')
+    .description('Remove a quote from a collection')
+    .action(async (collectionId: string, quoteId: string) => {
+      const client = await getClient()
+      await withSpinner('Removing quote from collection', () => client.collections.removeQuote(Number(collectionId), Number(quoteId)))
+      console.log(chalk.green(` Quote #${quoteId} removed from collection #${collectionId}`))
+    })
+}

package/src/commands/config.ts

@@ -0,0 +1,62 @@
+import type { Command } from 'commander'
+import { intro, outro, text, isCancel, cancel } from '@clack/prompts'
+import chalk from 'chalk'
+import { loadConfig, saveConfig, getConfigPath } from '../utils/config.js'
+
+export function registerConfigCommand(program: Command) {
+  program
+    .command('config')
+    .description('Manage configuration')
+    .alias('cfg')
+    .option('--api-key <key>', 'Set API key')
+    .option('--base-url <url>', 'Set base URL')
+    .option('--show', 'Show current config')
+    .action(async (options: Record<string, unknown>) => {
+      if (options.show) {
+        const config = await loadConfig()
+        const key = config.apiKey
+          ? `${config.apiKey.slice(0, 8)}...${config.apiKey.slice(-4)}`
+          : chalk.dim('not set')
+        console.log(`API key : ${key}`)
+        console.log(`Base URL: ${config.baseUrl ?? chalk.dim('default')}`)
+        console.log(`Config  : ${getConfigPath()}`)
+        return
+      }
+
+      const flags: Record<string, string> = {}
+      if (options.apiKey) flags.apiKey = options.apiKey as string
+      if (options.baseUrl) flags.baseUrl = options.baseUrl as string
+
+      if (Object.keys(flags).length > 0) {
+        const existing = await loadConfig()
+        await saveConfig({ ...existing, ...flags })
+        console.log(chalk.green('✓ Config updated'))
+        return
+      }
+
+      intro(chalk.bold('Verbatims Config'))
+
+      const existing = await loadConfig()
+
+      const apiKey = await text({
+        message: 'API key',
+        placeholder: 'vbt_xxx...',
+        defaultValue: existing.apiKey ?? '',
+      })
+      if (isCancel(apiKey)) cancel('Cancelled')
+
+      const baseUrl = await text({
+        message: 'Base URL (optional)',
+        placeholder: 'https://api.verbatims.com/v1',
+        defaultValue: existing.baseUrl ?? '',
+      })
+      if (isCancel(baseUrl)) cancel('Cancelled')
+
+      await saveConfig({
+        apiKey: apiKey as string,
+        baseUrl: (baseUrl as string) || undefined,
+      })
+
+      outro(chalk.green('Config saved'))
+    })
+}

package/src/commands/index.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander'
+import { registerQuotesCommand } from './quotes.js'
+import { registerAuthorsCommand } from './authors.js'
+import { registerReferencesCommand } from './references.js'
+import { registerTagsCommand } from './tags.js'
+import { registerCollectionsCommand } from './collections.js'
+import { registerSearchCommand } from './search.js'
+import { registerConfigCommand } from './config.js'
+
+export function registerCommands(program: Command) {
+  registerQuotesCommand(program)
+  registerAuthorsCommand(program)
+  registerReferencesCommand(program)
+  registerTagsCommand(program)
+  registerCollectionsCommand(program)
+  registerSearchCommand(program)
+  registerConfigCommand(program)
+}

package/src/commands/quotes.ts

@@ -0,0 +1,149 @@
+import type { Command } from 'commander'
+import { text, isCancel, cancel, confirm } from '@clack/prompts'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+import { browse } from '../utils/browse.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'table') as Format
+}
+
+export function registerQuotesCommand(program: Command) {
+  const quotes = program.command('quotes').description('Manage quotes')
+
+  quotes
+    .command('list')
+    .description('List quotes')
+    .option('--language <lang>', 'Filter by language')
+    .option('--limit <n>', 'Number of results', '20')
+    .option('--author <id>', 'Filter by author ID')
+    .option('--tag <name>', 'Filter by tag')
+    .option('--search <q>', 'Search in quote text')
+    .option('--sort-by <field>', 'Sort field')
+    .option('--sort-order <order>', 'Sort order (asc|desc)')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const { data, pagination } = await withSpinner('Fetching quotes', () =>
+        client.quotes.list({
+          language: options.language,
+          limit: Number(options.limit),
+          author_id: options.author ? Number(options.author) : undefined,
+          tag: options.tag,
+          search: options.search,
+          sort_by: options.sortBy,
+          sort_order: options.sortOrder as 'asc' | 'desc',
+        }),
+        format,
+      )
+
+      if (data) output(data, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  quotes
+    .command('get <id>')
+    .description('Get a quote by ID')
+    .action(async (id: string) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching quote', () => client.quotes.get(Number(id)), format)
+      output(data, format)
+    })
+
+  quotes
+    .command('create')
+    .description('Create a quote')
+    .option('--name <text>', 'Quote text')
+    .option('--language <lang>', 'Language')
+    .option('--author-id <id>', 'Author ID')
+    .option('--reference-id <id>', 'Reference ID')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const name = options.name ?? await text({ message: 'Quote text', validate: (v) => !v ? 'Required' : undefined })
+      if (isCancel(name)) cancel('Cancelled')
+
+      const language = options.language ?? await text({ message: 'Language', initialValue: 'fr' })
+      if (isCancel(language)) cancel('Cancelled')
+
+      const authorId = options.authorId ? Number(options.authorId) : undefined
+      const referenceId = options.referenceId ? Number(options.referenceId) : undefined
+
+      const { data } = await withSpinner('Creating quote', () =>
+        client.quotes.create({ content: name as string, name: name as string, language: language as string, author_id: authorId, reference_id: referenceId }),
+        format,
+      )
+      console.log(chalk.green(' Quote created'))
+      output(data, format)
+    })
+
+  quotes
+    .command('update <id>')
+    .description('Update a quote')
+    .option('--name <text>', 'Quote text')
+    .option('--language <lang>', 'Language')
+    .option('--author-id <id>', 'Author ID')
+    .option('--reference-id <id>', 'Reference ID')
+    .action(async (id: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const data_: Record<string, unknown> = {}
+      if (options.name) { data_.name = options.name; data_.content = options.name }
+      if (options.language) data_.language = options.language
+      if (options.authorId !== undefined) data_.author_id = options.authorId === 'null' ? null : Number(options.authorId)
+      if (options.referenceId !== undefined) data_.reference_id = options.referenceId === 'null' ? null : Number(options.referenceId)
+
+      const { data } = await withSpinner('Updating quote', () => client.quotes.update(Number(id), data_ as any), format)
+      console.log(chalk.green(' Quote updated'))
+      output(data, format)
+    })
+
+  quotes
+    .command('delete <id>')
+    .description('Delete a quote')
+    .option('--yes', 'Skip confirmation')
+    .action(async (id: string, options: Record<string, unknown>) => {
+      if (!options.yes) {
+        const confirmed = await confirm({ message: `Delete quote #${id}?` })
+        if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+      }
+
+      const client = await getClient()
+      await withSpinner('Deleting quote', () => client.quotes.delete(Number(id)))
+      console.log(chalk.green(` Quote #${id} deleted`))
+    })
+
+  quotes
+    .command('browse')
+    .description('Browse quotes interactively')
+    .option('--language <lang>', 'Filter by language')
+    .option('--author <id>', 'Filter by author ID')
+    .option('--tag <name>', 'Filter by tag')
+    .option('--search <q>', 'Search in quote text')
+    .option('--sort-by <field>', 'Sort field')
+    .option('--sort-order <order>', 'Sort order (asc|desc)')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      await browse(
+        (page) => client.quotes.list({
+          page,
+          language: options.language,
+          author_id: options.author ? Number(options.author) : undefined,
+          tag: options.tag,
+          search: options.search,
+          sort_by: options.sortBy,
+          sort_order: options.sortOrder as 'asc' | 'desc',
+        }),
+        format,
+      )
+    })
+}

package/src/commands/references.ts

@@ -0,0 +1,101 @@
+import type { Command } from 'commander'
+import { text, isCancel, cancel } from '@clack/prompts'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+import { browse } from '../utils/browse.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'table') as Format
+}
+
+export function registerReferencesCommand(program: Command) {
+  const refs = program.command('references').description('Manage references')
+
+  refs
+    .command('list')
+    .description('List references')
+    .option('--type <type>', 'Filter by type')
+    .option('--search <q>', 'Search references')
+    .option('--limit <n>', 'Number of results', '20')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data, pagination } = await withSpinner('Fetching references', () =>
+        client.references.list({ type: options.type, search: options.search, limit: Number(options.limit) }),
+        format,
+      )
+      output(data, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  refs
+    .command('get <id>')
+    .description('Get a reference by ID')
+    .action(async (id: string) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching reference', () => client.references.get(Number(id)), format)
+      output(data, format)
+    })
+
+  refs
+    .command('create')
+    .description('Create a reference')
+    .option('--name <name>', 'Reference name')
+    .option('--type <type>', 'Primary type')
+    .option('--description <text>', 'Description')
+    .option('--language <lang>', 'Original language')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const name = options.name ?? await text({ message: 'Reference name', validate: (v) => !v ? 'Required' : undefined })
+      if (isCancel(name)) cancel('Cancelled')
+
+      const primaryType = options.type ?? await text({ message: 'Primary type' })
+      if (isCancel(primaryType)) cancel('Cancelled')
+
+      const { data } = await withSpinner('Creating reference', () =>
+        client.references.create({ name: name as string, type: primaryType as string, primary_type: primaryType as string, description: options.description ?? null, language: options.language, original_language: options.language }),
+        format,
+      )
+      console.log(chalk.green(' Reference created'))
+      output(data, format)
+    })
+
+  refs
+    .command('update <id>')
+    .description('Update a reference')
+    .option('--name <name>', 'Reference name')
+    .option('--description <text>', 'Description')
+    .action(async (id: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      const data_: Record<string, unknown> = {}
+      if (options.name) { data_.name = options.name }
+      if (options.description !== undefined) data_.description = options.description
+
+      const { data } = await withSpinner('Updating reference', () => client.references.update(Number(id), data_ as any), format)
+      console.log(chalk.green(' Reference updated'))
+      output(data, format)
+    })
+
+  refs
+    .command('browse')
+    .description('Browse references interactively')
+    .option('--type <type>', 'Filter by type')
+    .option('--search <q>', 'Search references')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      await browse(
+        (page) => client.references.list({ page, type: options.type, search: options.search }),
+        format,
+      )
+    })
+}

package/src/commands/search.ts

@@ -0,0 +1,43 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+import { browse } from '../utils/browse.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'table') as Format
+}
+
+export function registerSearchCommand(program: Command) {
+  program
+    .command('search <query>')
+    .description('Search quotes, authors, or references')
+    .option('--type <type>', 'Type to search: quotes|authors|references', 'quotes')
+    .option('--limit <n>', 'Number of results', '20')
+    .action(async (query: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data, pagination } = await withSpinner('Searching', () =>
+        client.search.query({ q: query, type: options.type as 'quotes' | 'authors' | 'references', limit: Number(options.limit) }),
+        format,
+      )
+      output(data, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  program
+    .command('search-browse <query>')
+    .description('Browse search results interactively')
+    .option('--type <type>', 'Type to search: quotes|authors|references', 'quotes')
+    .action(async (query: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      await browse(
+        (page) => client.search.query({ q: query, type: options.type as 'quotes' | 'authors' | 'references', page }),
+        format,
+      )
+    })
+}

package/src/commands/tags.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander'
+import { getClient } from '../utils/client.js'
+import { output } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+
+export function registerTagsCommand(program: Command) {
+  program
+    .command('tags')
+    .description('Manage tags')
+    .command('list')
+    .description('List tags')
+    .action(async () => {
+      const client = await getClient()
+      const format = (program.opts().format ?? 'table') as 'table' | 'json' | 'plain'
+      const { data } = await withSpinner('Fetching tags', () => client.tags.list(), format)
+      output(data, format)
+    })
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { registerCommands } from './commands/index.js'
+import { setSilent } from './utils/spinner.js'
+
+process.on('unhandledRejection', (err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
+
+const program = new Command()
+
+program
+  .name('verbatims')
+  .description('CLI for the Verbatims quotes API')
+  .option('--api-key <key>', 'API key (overrides config and env)')
+  .option('--format <type>', 'Output format: table|json|plain', 'table')
+  .showHelpAfterError()
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals()
+    if (opts.format === 'json') setSilent(true)
+  })
+
+registerCommands(program)
+
+program.parse()

package/src/utils/browse.ts

@@ -0,0 +1,88 @@
+import { formatTable, type Format } from './format.js'
+import type { PaginationMeta } from '@verbatims/sdk'
+
+type PageFetcher = (page: number) => Promise<{
+  data?: unknown[]
+  pagination?: PaginationMeta
+}>
+
+export async function browse(fetchPage: PageFetcher, format: Format): Promise<void> {
+  if (!process.stdin.isTTY) {
+    console.error('Browse mode requires an interactive terminal.')
+    process.exit(1)
+  }
+
+  let page = 1
+  let hasMore = false
+
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+
+  const render = async () => {
+    const result = await fetchPage(page)
+    const items = result.data ?? []
+    const pagination = result.pagination
+    hasMore = pagination?.hasMore ?? false
+
+    console.clear()
+
+    if (items.length === 0) {
+      console.log('No results')
+      return false
+    }
+
+    const allKeys = Object.keys(items[0] as Record<string, unknown>)
+    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference']
+    const columns = keyOrder
+      .filter((k) => allKeys.includes(k))
+      .map((k) => ({ key: k, label: k }))
+
+    const table = formatTable(items as Record<string, unknown>[], columns)
+    console.log(table)
+
+    if (pagination) {
+      console.log(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`)
+    }
+
+    if (hasMore || page > 1) {
+      const nav = []
+      if (page > 1) nav.push('◀ p')
+      if (hasMore) nav.push('n ▶')
+      nav.push('q quit')
+      console.log(`\n${nav.join('  │  ')}`)
+    } else {
+      console.log('\nq quit')
+    }
+
+    return true
+  }
+
+  await render()
+
+  const onKey = async (key: string) => {
+    if (key === 'q' || key === '\u001b') {
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+      process.stdin.removeListener('data', onData)
+      console.log()
+      return
+    }
+
+    if ((key === 'n' || key === ' ' || key === '\u001b[C') && hasMore) {
+      page++
+      await render()
+    }
+
+    if ((key === 'p' || key === '\u001b[D') && page > 1) {
+      page--
+      await render()
+    }
+  }
+
+  const onData = (buf: Buffer) => {
+    const key = buf.toString()
+    onKey(key)
+  }
+
+  process.stdin.on('data', onData)
+}

package/src/utils/client.ts

@@ -0,0 +1,18 @@
+import { VerbatimsClient } from '@verbatims/sdk'
+import { loadConfig } from './config.js'
+
+const DEFAULT_BASE_URL = 'https://verbatims.cc/api/v1'
+
+export async function getClient(): Promise<VerbatimsClient> {
+  const config = await loadConfig()
+  const apiKey = process.env.VERBATIMS_API_KEY ?? config.apiKey
+
+  if (!apiKey) {
+    console.error('Missing API key. Set VERBATIMS_API_KEY env var or run `verbatims config init`.')
+    process.exit(1)
+  }
+
+  return new VerbatimsClient(apiKey, {
+    baseUrl: process.env.VERBATIMS_BASE_URL ?? config.baseUrl ?? DEFAULT_BASE_URL,
+  })
+}

package/src/utils/config.ts

@@ -0,0 +1,32 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const CONFIG_DIR = join(homedir(), '.config', 'verbatims')
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json')
+
+export interface Config {
+  apiKey?: string
+  baseUrl?: string
+}
+
+export function getConfigPath(): string {
+  return CONFIG_PATH
+}
+
+export async function loadConfig(): Promise<Config> {
+  try {
+    const raw = await readFile(CONFIG_PATH, 'utf-8')
+    return JSON.parse(raw) as Config
+  } catch {
+    return {}
+  }
+}
+
+export async function saveConfig(config: Config): Promise<void> {
+  if (!existsSync(CONFIG_DIR)) {
+    await mkdir(CONFIG_DIR, { recursive: true })
+  }
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8')
+}

package/src/utils/format.ts

@@ -0,0 +1,173 @@
+import chalk from 'chalk'
+
+export type Format = 'table' | 'json' | 'plain'
+
+const stripAnsi = (s: string) => s.replace(/\x1B\[[0-?9;]*[mK]/g, '')
+
+function padVisual(s: string, max: number): string {
+  const padLen = Math.max(0, max - stripAnsi(s).length)
+  return s + ' '.repeat(padLen)
+}
+
+function wordWrap(s: string, max: number): string[] {
+  if (stripAnsi(s).length <= max) return [s]
+  const lines: string[] = []
+  let current = ''
+  for (const word of s.split(' ')) {
+    const cleanWord = stripAnsi(word)
+    const cleanCurrent = stripAnsi(current)
+    if (cleanCurrent.length + cleanWord.length + (cleanCurrent.length > 0 ? 1 : 0) > max) {
+      if (cleanCurrent.length > 0) {
+        lines.push(current)
+        current = word
+      } else {
+        lines.push(word)
+        current = ''
+      }
+    } else {
+      current += (current ? ' ' : '') + word
+    }
+  }
+  if (current) lines.push(current)
+  return lines
+}
+
+function terminalWidth(): number {
+  return process.stdout.columns ?? 100
+}
+
+function formatCell(value: unknown): string {
+  if (value === null || value === undefined) return chalk.dim('—')
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>
+    if ('name' in obj && typeof obj.name === 'string') return obj.name
+    if ('views' in obj && 'likes' in obj) {
+      const v = obj.views ?? 0
+      const l = obj.likes ?? 0
+      return `${chalk.dim('👁')} ${v} ${chalk.dim('❤')} ${l}`
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => {
+        if (typeof item === 'object' && item && 'name' in item) return (item as { name: string }).name
+        return String(item)
+      }).join(', ') || chalk.dim('—')
+    }
+    return chalk.dim('…')
+  }
+  if (typeof value === 'boolean') return value ? chalk.green('✓') : chalk.dim('✗')
+  return String(value)
+}
+
+const FIXED = ['id', 'language', 'featured', 'stats']
+
+export function formatTable<T extends Record<string, unknown>>(
+  items: T[],
+  columns: { key: keyof T; label: string }[],
+): string {
+  if (items.length === 0) return chalk.dim('No results')
+
+  const colSizes = columns.map((col) => {
+    return Math.max(
+      col.label.length,
+      ...items.map((item) => stripAnsi(formatCell(item[col.key])).length),
+    )
+  })
+
+  const total = colSizes.reduce((a, b) => a + b + 3, 0) + 1
+  const terminal = terminalWidth()
+
+  if (total > terminal) {
+    const overflow = total - terminal
+    const contentIdx = columns.findIndex((c) => c.key === 'content' || c.key === 'name')
+    if (contentIdx !== -1) {
+      colSizes[contentIdx] = Math.max(24, colSizes[contentIdx]! - overflow)
+    }
+  }
+
+  const secondTotal = colSizes.reduce((a, b) => a + b + 3, 0) + 1
+  if (secondTotal > terminal) {
+    const overflow2 = secondTotal - terminal
+    const flexIdxs = columns
+      .map((c, i) => ({ key: c.key as string, i }))
+      .filter((c) => !FIXED.includes(c.key) && c.key !== 'content' && c.key !== 'name')
+    const flexTotal = flexIdxs.reduce((s, { i }) => s + colSizes[i]!, 0)
+    if (flexTotal > 0) {
+      for (const { i } of flexIdxs) {
+        colSizes[i] = Math.max(3, colSizes[i]! - Math.round(overflow2 * colSizes[i]! / flexTotal))
+      }
+    }
+  }
+
+  const sep = (left: string, mid: string, right: string) =>
+    left + columns.map((col, i) => '─'.repeat(colSizes[i]! + 2) + (i < columns.length - 1 ? mid : '')).join('') + right
+
+  const cell = (vals: string[]) =>
+    '│' + vals.map((v, i) => ` ${padVisual(v, colSizes[i]!)} │`).join('')
+
+  const headerLine = cell(columns.map((col, i) => chalk.bold(padVisual(col.label, colSizes[i]!))))
+
+  const rowParts = items.map((item) => {
+    const cellLines = columns.map((col, i) => wordWrap(formatCell(item[col.key]), colSizes[i]!))
+    const maxLines = Math.max(...cellLines.map((l) => l.length), 1)
+    const lines: string[] = []
+    for (let line = 0; line < maxLines; line++) {
+      const vals = columns.map((_col, i) => cellLines[i]![line] ?? '')
+      lines.push(cell(vals))
+    }
+    return lines.join('\n')
+  })
+
+  const top = sep('┌', '┬', '┐')
+  const mid = sep('├', '┼', '┤')
+  const bot = sep('└', '┴', '┘')
+
+  return [top, headerLine, mid, ...rowParts, bot].join('\n')
+}
+
+export function output(data: unknown, format: Format): void {
+  if (format === 'json') {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      console.log(chalk.dim('No results'))
+      return
+    }
+
+    const allKeys = Object.keys(data[0] as Record<string, unknown>)
+    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference']
+    const columns = keyOrder
+      .filter((k) => allKeys.includes(k))
+      .map((k) => ({ key: k, label: k }))
+
+    if (format === 'table') {
+      console.log(formatTable(data as Record<string, unknown>[], columns))
+    } else {
+      for (const item of data) {
+        console.log(formatItem(item as Record<string, unknown>))
+        console.log()
+      }
+    }
+    return
+  }
+
+  if (typeof data === 'object' && data !== null) {
+    if (format === 'table') {
+      console.log(JSON.stringify(data, null, 2))
+    } else {
+      console.log(formatItem(data as Record<string, unknown>))
+    }
+    return
+  }
+
+  console.log(String(data))
+}
+
+function formatItem(item: Record<string, unknown>): string {
+  return Object.entries(item)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${chalk.bold(k)}: ${formatCell(v)}`)
+    .join('\n')
+}

package/src/utils/spinner.ts

@@ -0,0 +1,28 @@
+import { spinner as clackSpinner } from '@clack/prompts'
+import type { Format } from './format.js'
+
+let silentMode = false
+
+export function setSilent(silent: boolean) {
+  silentMode = silent
+}
+
+export function isSilent(): boolean {
+  return silentMode
+}
+
+export async function withSpinner<T>(label: string, fn: () => Promise<T>, format?: Format): Promise<T> {
+  if (format === 'json' || silentMode) {
+    return fn()
+  }
+  const s = clackSpinner()
+  s.start(label)
+  try {
+    const result = await fn()
+    s.stop('Done')
+    return result
+  } catch (err) {
+    s.stop('Error')
+    throw err
+  }
+}