@onebooks/cli

The OneBooks developer CLI (onebooks): sign in to the developer console, list your apps, deploy and test hosted functions, and scaffold a new embedded app from a starter template.

Zero runtime dependencies — node:util's parseArgs, the global fetch, and node:readline for prompts. ESM, TypeScript, Node ≥ 20.

Install

npm install -g @onebooks/cli
onebooks --version

Or run any command without a global install: npx @onebooks/cli <command>.

Commands

onebooks login [--api <url>] [--email <email>]
onebooks logout
onebooks whoami [--json]
onebooks apps list [--org <slug-or-id>] [--json]
onebooks functions list --app <appId> [--json]
onebooks functions deploy --app <appId> --name <fn> --file <path>
                           [--events a,b] [--egress host1,host2] [--description "..."]
                           [--activate] [--notes "..."] [--json]
                           (--events is required when <fn> doesn't exist yet)
onebooks functions logs --app <appId> --name <fn>
                         [--status QUEUED|RUNNING|SUCCEEDED|FAILED|SKIPPED] [--cursor <runId>] [--json]
onebooks functions test --app <appId> --name <fn>
                         --business <sandboxBusinessId> --event <type>
                         [--data '{"...":"..."}'] [--json]
onebooks init <dir> [--template embedded-node]

Every command supports -h/--help. Data-returning commands support --json for the raw API response; without it, output is a generic human-friendly rendering (a table for an array of objects, key: value lines for a single object).

login

Prompts for email and password (password input is masked), signs in against {apiBase}/api/dev-auth/sign-in/email, and saves the session to ~/.config/onebooks/config.json (created at mode 0600 — it holds a bearer token). --api <url> points at a non-default API (defaults to the last one used, or https://api.getonebooks.com).

apps list

Lists your apps across every organization you belong to. The id column — not clientId — is what every functions command's --app flag expects; the developer console's own routes (/developer/apps/:id/...) key on the internal id, while clientId is the public OAuth client_id used everywhere else (authorize URLs, token requests, …).

functions deploy

Creates the function if a function with that --name doesn't already exist on --app (via --events/--egress/--description, comma-separated for the first two), uploads --file's contents as a new version, and — with --activate — makes that version live immediately. Source is capped at 1 MB, matching the hosted runtime's own limit; this is checked locally before uploading.

• Creating a function requires --events (a function must run on at least one event): without it the command stops with a usage error before creating or uploading anything.
• --egress hostnames are lowercased (hostnames are case-insensitive and the API rejects mixed case) and de-duplicated.
• For an existing function, --events, --egress and --description are ignored (the command says so) — change them on the app's Functions tab in the developer console; deploy only uploads a new version.
• Upload one self-contained ES module — the hosted sandbox loads only that file, so bundle any imports first.

functions test

Fires a synthetic event of --event's type against --business (one of your organization's sandbox tenants, with the app installed). --data overrides the event catalog's sample payload for that event type with your own JSON, if given.

init

onebooks init my-app
cd my-app
cp .env.example .env
npm install
node server.mjs

Scaffolds developer-sdk/templates/embedded-node (currently the only template) into a new or empty directory — see that template's own README for the full walkthrough (console setup, scopes, sandbox, running behind a tunnel, deploying its example function).

The template declares @onebooks/node as file:../../node, which only resolves inside the OneBooks repository, so init rewrites that dependency — to ^<CLI version> from npm, or to the local developer-sdk/node folder when the CLI runs from a OneBooks source checkout — and prints what it chose:

• run from a OneBooks source checkout (developer-sdk/cli), it points at the node/ package next to cli/ by absolute path — "@onebooks/node": "file:/…/node" — and, if that package hasn't been built, prints the npm install && npm run build command to run first (npm links the folder as-is, so it needs its dist/ and its own node_modules);
• otherwise it writes the ^<CLI version> range for npm.

The template's .gitignore (which keeps .env and data/ — your client secret and stored tokens — out of git) ships inside the CLI as _gitignore, because npm renames a packed .gitignore; init restores the real name.

Config file

~/.config/onebooks/config.json:

{
  "apiBase": "https://api.getonebooks.com",
  "consoleToken": "…"
}

Always written at mode 0600. onebooks logout clears consoleToken but keeps apiBase. Override the config directory (for tests, or to run two isolated sessions) with the ONEBOOKS_CONFIG_DIR environment variable.

Development

npm install
npm run build       # tsc -> dist/, copies developer-sdk/templates/* -> dist/templates, chmod +x dist/bin.js
npm test            # node:test via tsx — no network; config tests use a throwaway ONEBOOKS_CONFIG_DIR
npm run typecheck

After building, the real binary works standalone:

node dist/bin.js --help
node dist/bin.js init /tmp/try-it

Tests cover argument parsing (missing required flags, unknown subcommands, --help on every command), functions deploy against a fake console API (--events required on create, lowercased --egress), init (dependency rewrite, _gitignore restore) and config file handling (mode 0600, default values, round-tripping, logout preserving apiBase) — see test/commands.test.ts and test/config.test.ts. login's HTTP/token logic is tested directly via the exported signIn() helper (with a fake fetch) rather than by simulating a terminal prompt.

License

MIT