CLI Reference

The worm CLI is the command-line interface for S3WORM. It handles schema initialization, data import, validation, local development, code generation, and LLM content output.

Quick Reference Cheat Sheet

Installation

pnpm add -g @decoperations/s3worm

The CLI is available as the worm command after installation.

Commands

worm init

Initialize a new S3WORM project in the current directory. Creates the .worm/ directory structure with a starter schema and example data.

worm init

What It Creates

.worm/
  schema.json           # Schema definition with example models
  import.prompt.md      # AI import prompt template
  data/                 # Local data directory (filesystem transport root)
  generated/            # Output directory for codegen
  examples/             # Example data files

The generated schema.json includes sensible defaults: symbols, common dynamic types (uuid, evm), operators (auto, seq), and a "root" storage layout.

worm import

Scan the .worm/data/ directory, discover existing files, and infer schema paths from the file structure. Can use AI or heuristic mode for schema inference.

worm import [options]

Options

Behavior

1. Recursively scans .worm/data/ for all files
2. Groups files by directory structure
3. Infers path DSL patterns from file paths
4. In AI mode: sends discovered paths and file samples to OpenAI for schema generation
5. In heuristic mode: applies rule-based inference (directory depth, naming conventions)
6. Writes inferred paths and models to schema.json

Example

# AI-powered import (requires OPENAI_API_KEY)
worm import

# Heuristic-only import
worm import --no-ai

# Use a specific OpenAI model
worm import --model gpt-4.1

worm lint

Validate the schema definition. Checks for structural correctness, symbol consistency, path validity, dynamic type references, rule conflicts, and model integrity.

worm lint

What It Validates

Output

$ worm lint

Linting .worm/schema.json...

  ERROR  [MODEL_REF_MISSING] Invoice.customerId refs "Customer" but model "Customer" not found
  WARN   [RULE_ACL_OVERLAP] Rule "admin-only" overlaps with model ACL on "Invoice"

1 error, 1 warning

Exits with code 1 if any errors are found. Warnings do not affect the exit code.

worm dev

Start local development mode. Uses the filesystem transport to read and write entities from .worm/data/. Watches for file changes and reports mutations in real time.

worm dev [path]

Arguments

Behavior

1. Loads schema.json from the specified directory
2. Creates a LocalFsTransport pointing at the data/ subdirectory
3. Validates the schema on startup
4. Watches the data/ directory for file changes
5. On change: detects the affected model and entity, logs the mutation

Example

# Start dev mode with default path
worm dev

# Point to a custom .worm directory
worm dev ./my-project/.worm

The dev server provides a live feedback loop: edit JSON files in .worm/data/ and see changes reflected immediately. This is the foundation for local-first development with S3WORM.

worm codegen

Generate TypeScript interfaces and optional Zod validation schemas from your schema.json models. The output gives you type-safe entity types, repository aliases, and a model map for generic helpers.

worm codegen [options]

Options

Output Files

Output Directory Resolution

The output directory is determined in this order:

1. --output / -o CLI flag
2. generatedDir field in your schema.json
3. .worm/generated (default fallback)

Type Mapping

Auto-fields (createdAt, updatedAt) are inherited from SchemaEntity in the TypeScript output but included explicitly in Zod schemas. Optional fields get ? in TypeScript and .optional() in Zod. Default values are preserved in Zod via .default().

Example

# Generate TypeScript interfaces only
worm codegen

# Generate TypeScript + Zod schemas
worm codegen --zod

# Custom output directory
worm codegen --zod --output src/generated

Generated TypeScript (Example)

Given a schema with a Customer model:

// Auto-generated by `worm codegen` — do not edit
import type { SchemaEntity, EntityRef, SchemaRepository } from "@decoperations/s3worm";

/** Customer entity */
export interface Customer extends SchemaEntity {
  name: string;
  email: string;
  company?: string;
  status?: "active" | "inactive" | "churned";
  tags?: string[];
}

export type CustomerRepository = SchemaRepository;

/** Union of all model names */
export type ModelName = "Customer";

/** Map from model name to entity type */
export interface ModelMap {
  Customer: Customer;
}

Generated Zod Schema (Example)

With --zod:

// Auto-generated by `worm codegen` — do not edit
import { z } from "zod";

export const CustomerSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string(),
  company: z.string().optional(),
  status: z.enum(["active", "inactive", "churned"]).default("active"),
  tags: z.array(z.string()).optional(),
  createdAt: z.string(),
  updatedAt: z.string(),
});

export type Customer = z.infer<typeof CustomerSchema>;

worm llms

Generate an llms.txt file for AI and LLM consumption. Outputs a structured text representation of the schema that can be used as context for AI assistants.

worm llms [options]

Options

Example

# Print to stdout
worm llms

# Write to a file
worm llms --output llms.txt

The output includes the full schema definition, model descriptions, field types, path patterns, and relationship information in a format optimized for LLM context windows.

worm version

Print the current CLI version.

worm version

$ worm version
worm v0.5.1

Environment Variables

WORM_ROOT

By default, the CLI looks for .worm/ in the current working directory. Set WORM_ROOT to override:

export WORM_ROOT=/path/to/project/.worm
worm lint  # uses /path/to/project/.worm/schema.json

OPENAI_API_KEY

Required when running worm import in AI mode. The CLI uses this key to call the OpenAI API for schema inference.

export OPENAI_API_KEY=sk-...
worm import

WORM_OPENAI_MODEL

Override the default OpenAI model used for AI import. Defaults to gpt-4.1-mini.

export WORM_OPENAI_MODEL=gpt-4.1
worm import

Directory Structure

After worm init, your project has this structure:

project/
  .worm/
    schema.json          # Schema definition
    import.prompt.md     # AI import prompt
    data/                # Local entity data (filesystem transport)
      org/
        customers/
          abc-123/
            profile.json
        settings/
          config.json
    generated/           # Codegen output
      models.ts          # Generated TypeScript interfaces
    examples/            # Example files

The data/ directory mirrors the S3 bucket structure. Paths in schema.json map directly to directory paths under data/:

Path:   #org/@customers/(id:uuid)/[profile].json
Local:  .worm/data/org/customers/{uuid}/profile.json
S3 key: org/customers/{uuid}/profile.json

Coming Soon

These commands are planned for upcoming releases. See the Roadmap for details.

Exit Codes