@octaviaflow/cli

Command-line companion for the OctaviaFlow Design System. Scaffolds projects, adds components, validates config, and sets up @octaviaflow/logger.

Installation

The CLI is usually invoked via npx, but can also be installed locally:

npm install -D @octaviaflow/cli

Binary: ods.

Requires Node.js >= 22.

Commands

ods init                      Initialize OctaviaFlow in your project
ods add <component...>        Add components to your project
ods generate                  Generate token files from config
ods check                     Validate your OctaviaFlow config
ods upgrade                   Upgrade OctaviaFlow packages
ods scaffold <type> <name>    Scaffold a component, plugin, or tool  (alias: new)
ods logger <verb>             Manage @octaviaflow/logger  (verbs: init, doctor, test)

Global flags: --help, --version.

ods logger — Logger setup

A dedicated namespace for installing and configuring @octaviaflow/logger without touching the rest of the design system. Runs standalone — it doesn't pull in UI tokens or component presets.

ods logger init

Interactive setup. Detects the project's framework (Next.js, Vite, Express, etc.) and writes a logger.config.ts tailored to your answers.

Prompts cover:

• Service type — backend, engine, worker, scheduler, or ui.
• Runtime mode — development, staging, or production.
• Log level and format — info/debug/warn/trace and json/pretty/compact/ecs.
• Targets (multiselect) — console, file, s3, gdrive, onedrive, dropbox. Disabled targets are written into the config commented-out so they're easy to turn on later.
• Per-target specifics — bucket + region + prefix for S3, folderId for Google Drive, folder paths for OneDrive and Dropbox.
• Retention preset — Standard (10 MB × 10 files × 30 days), Lean (1 MB × 5 × 7), Generous (50 MB × 30 × 90), or Custom.

Side effects (all optional, confirmed inline):

• Writes logger.config.ts (default path; override via --config <path>).
• Writes src/logger.ts bootstrap that calls createLoggerFromConfig(config).
• Appends logs/ to .gitignore if not already present.
• Installs @octaviaflow/logger via npm (skip with --no-install).

Credentials for cloud targets are never written to logger.config.ts. The config references env var names only — the transport reads the values from process.env at construction time.

Flags:

• --config <path> — explicit config file path (default: ./logger.config.ts).
• --no-install — skip the npm install step.

ods logger doctor

Non-interactive audit. Useful on CI or pre-deploy.

• Resolves logger.config.{ts,mjs,js,json} in cwd.
• Parses the file (via dynamic import() or JSON.parse).
• Runs validateLoggerFileConfig from @octaviaflow/logger/config and reports every issue — warnings and errors both.
• For each enabled cloud target, checks that its required env vars are set in process.env.
• For the file target, probes that the log directory exists and is writable (via mkdir + write + unlink).

Exits 0 on clean, 0 with message on warnings, 1 on errors.

Flag: --config <path>.

ods logger test

End-to-end smoke test. Emits one line at each level (trace, debug, info, warn, error) through every configured transport, then flushes and closes. For cloud transports this also triggers the retention sweep.

Flag: --config <path>.

Development

npm run build      # tsup dual ESM+CJS
npm run test       # vitest
npm run lint       # biome

License

Apache-2.0