@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.tsandsrc/__generated__/server-types.d.ts
Import boundary in generated projects:
src/defs/**may import shared types from@sdk/server-typessrc/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