CLI Usage

Synode includes a CLI for generating synthetic data from config files. Install it globally or use it as a project dependency.

Install

# Global install
npm install -g @synode/cli

# Or as a project dependency (included when you run synode init)
npm install @synode/cli

Quick Start

# Scaffold a new project interactively
synode init

# Generate data
synode generate synode.config.ts

# Validate config without generating
synode validate synode.config.ts

# Show help
synode --help
synode generate --help

Commands

synode init [dir]

Interactive project scaffolder. Creates a complete Synode project with config, dependencies, and optional example journeys.

synode init                  # Prompts for project name
synode init my-project       # Creates my-project/ directory

The scaffolder prompts for:

1. Project name — directory to create
2. Adapters — which output adapters to install (File, HTTP, BigQuery, Stream, Composite)
3. Example journey — include a working browse-and-purchase example
4. CLAUDE.md sections — AI assistant context (API reference, error codes, architecture)
5. Package manager — pnpm, npm, or yarn

After scaffolding, it installs dependencies and shows next steps using your chosen package manager.

synode generate <config>

Loads the config file and runs event generation. Shows progress with timing and events/sec.

synode generate synode.config.ts
synode generate synode.config.ts --users 5000 --lanes 4
synode generate synode.config.ts --output events.jsonl
synode generate synode.config.ts --output ./out/ --format csv
synode generate synode.config.ts --workers 8 --debug

When --output is a directory (or a path without an extension), the CLI automatically creates a file named events.{ext} inside it.

synode validate <config>

Validates the config file structure without generating any events. Shows a pass/fail summary for each journey. Exits with code 0 on success, 1 on failure.

synode validate synode.config.ts

Output:

  Validating 3 journeys...

  ✓ browse-session
  ✓ purchase-flow
  ✗ checkout — bounceChance must be between 0 and 1

  2 passed, 1 failed

Flags

All flags apply to the generate command. They override config file values.

Flag	Short	Type	Description
--users <n>	-u	number	Override user count
--lanes <n>	-l	number	Override lane count
--workers <n>	-w	number	Enable worker threads with N workers
--output <path>	-o	string	Output file or directory path
--format <fmt>	-f	string	Output format: json, jsonl, csv
--debug		boolean	Enable telemetry collection
--dry-run		boolean	Validate config, generate 1 user only
--quiet	-q	boolean	Suppress progress output
--version	-V		Show version number
--help	-h		Show help for any command

Config File Format

The config file must export (default or named) a SynodeConfig object. Run synode init to scaffold one, then customize.

import { defineJourney, definePersona, weighted } from '@synode/core';

export default {
  journeys: [browseJourney, purchaseJourney],
  persona: myPersona,
  datasets: [productsDef],
  options: {
    users: 1000,
    lanes: 4,
    debug: true,
    adapter: {
      type: 'file',
      path: './output/events.jsonl',
      format: 'jsonl',
    },
  },
};

SynodeConfig Shape

interface SynodeConfig {
  journeys: Journey[]; // required, non-empty
  persona?: PersonaDefinition;
  datasets?: DatasetDefinition[];
  preloadedDatasets?: Dataset[];
  options?: {
    users?: number;
    lanes?: number;
    adapter?: AdapterConfig;
    debug?: boolean;
    telemetryPath?: string;
    startDate?: Date;
    endDate?: Date;
    eventSchema?: EventSchemaConfig;
    workerModule?: string;
    workers?: number;
  };
}

AdapterConfig

The CLI supports two adapter types via config:

// Console output (default — writes to stdout)
adapter: { type: 'console' }

// File output
adapter: { type: 'file', path: './output/events.jsonl', format: 'jsonl' }

When --output is passed as a flag, it creates a file adapter. Format is inferred from the file extension or from the --format flag.

Example Workflow

# 1. Scaffold a new project
synode init my-cdp-data

# 2. Enter the project
cd my-cdp-data

# 3. Edit synode.config.ts with your journeys, persona, datasets

# 4. Dry run to validate
pnpm generate -- --dry-run

# 5. Generate a small sample
synode generate synode.config.ts --users 100 --output ./output/

# 6. Full generation with parallelism
synode generate synode.config.ts --users 50000 --lanes 8 --output ./output/events.jsonl

# 7. Worker thread generation for large datasets
synode generate synode.config.ts --users 100000 --workers 4 --debug

Error Handling

Errors include the CLI version and a pre-filled GitHub issue link:

Error: Config file not found: /path/to/missing.ts

synode v2.0.5 on v22.0.0
Report: https://github.com/digitl-cloud/synode/issues?title=...

Set DEBUG=1 to include the full stack trace in error output.