@edgespark/cli

EdgeSpark CLI - Create and manage your EdgeSpark projects.

Installation

npm install -g @edgespark/cli

Usage

Initialize a new project

# With specific AI agent (--agent is required)
edgespark init my-project --agent claude    # Creates CLAUDE.md
edgespark init my-project --agent gemini    # Creates GEMINI.md
edgespark init my-project --agent codex     # Creates AGENTS.md

Agent options: claude, codex, gemini (others fall back to AGENTS.md)

Pull from EdgeSpark platform

edgespark pull

Pulls the latest generated artifacts from your EdgeSpark project:

• schema files into src/__generated__/
• SDK types into src/__generated__/edgespark.d.ts and src/__generated__/server-types.d.ts

Import boundary in generated projects:

• src/defs/** may import shared types from @sdk/server-types
• src/defs/** must not import from "edgespark"
• route and application code should import runtime SDK values from "edgespark"

You can also pull selectively:

edgespark pull schema
edgespark pull types

Manage custom domains

Custom domains are production-only. Staging custom domains are not supported.

# Start domain setup and get the required DNS records
edgespark domain add app.example.com

# Poll verification and activate routing once DNS is in place
edgespark domain verify app.example.com

# Inspect current status, DNS records, and any warnings
edgespark domain status app.example.com

# List all custom domains for the current project
edgespark domain list

# Remove a custom domain and release the claim
edgespark domain remove app.example.com

domain add and domain status always return the manual DNS records needed for setup.
When EdgeSpark can build a supported Domain Connect setup URL, it is returned as a convenience, but manual DNS remains the source of truth.

Help

# General help
edgespark --help

# Command-specific help
edgespark init --help
edgespark pull --help

Commands

| Command | Description | |---------|-------------| | edgespark init <name> --agent <name> | Initialize a new EdgeSpark project | | edgespark db generate | Generate migration files from src/defs/db_schema.ts | | edgespark db migrate | Apply pending migrations to the project database | | edgespark db studio | Open a database browser for the project database | | edgespark db check | Validate local migration consistency | | edgespark db sql | Run ad-hoc SQL against the project database | | edgespark domain add <hostname> | Start custom domain setup and print DNS records | | edgespark domain verify <hostname> | Check whether a custom domain is active | | edgespark domain status <hostname> | Show current custom domain status and DNS guidance | | edgespark domain list | List custom domains for the current project | | edgespark domain remove <hostname> | Remove a custom domain from the project | | edgespark pull | Pull schemas and types from EdgeSpark | | edgespark pull schema | Pull platform-managed system DB schema | | edgespark pull types | Pull generated SDK type declarations |

Project Structure

After running edgespark init, your project will have:

my-project/
├── src/
│   ├── index.ts              # Your API routes (Hono)
│   ├── __generated__/        # Generated artifacts (pulled from platform)
│   │   ├── index.ts          # Barrel exports
│   │   ├── sys_schema.ts     # System database schema (Drizzle ORM)
│   │   ├── sys_relations.ts  # System relation definitions (if any)
│   │   ├── storage_schema.ts # Storage bucket definitions
│   │   ├── edgespark.d.ts    # What user code can import from "edgespark" and "edgespark/*"
│   │   └── server-types.d.ts # Shared SDK type definitions
├── edgespark.toml            # Project configuration
├── package.json
├── tsconfig.json
└── AGENTS.md                 # AI coding agent instructions (or CLAUDE.md / GEMINI.md)

Development

npm run build:dev   # tsc (for development/tests)
npm run dev         # tsc --watch
npm test            # run tests
npm run link        # build bundle + npm link for local testing

Publishing

prepublishOnly automatically runs esbuild + copies templates before any publish.

1. Beta release

npm version <version>-beta.0       # first beta for a new version (manual)
npm publish --tag beta             # publish to "beta" tag (latest untouched)

2. Iterate on beta

npm version prerelease             # auto-bumps beta.0 → beta.1 → beta.2
npm publish --tag beta

3. Test beta

npm install -g @edgespark/cli@beta # install globally
edgespark --version                # verify
npx @edgespark/cli@beta --version  # or test without global install

4. Graduate to release

npm version patch                  # 0.0.X-beta.N → 0.0.X (clean version)
npm publish                        # publishes to "latest" tag

Version commands cheat sheet

| Command | Example | |---------|---------| | npm version <version>-beta.0 | First beta (manual) | | npm version prerelease | beta.0 → beta.1 | | npm version patch | 0.0.10-beta.2 → 0.0.10 | | npm version minor | → 0.1.0 | | npm version major | → 1.0.0 |

License

MIT