EdgeSpark

https://docs.edgespark.dev
Admin
EdgeSpark is a platform for deploying full-stack Hono applications to Cloudflare's edge network with...
Tokens:47,280
Snippets:677
Trust Score:5.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start local development server

Source: https://docs.edgespark.dev/cli/commands

Start the local development server. You can specify a different port or reset the development state before starting.

```bash
edgespark dev
```

```bash
edgespark dev --port <number>
```

```bash
edgespark dev --reset
```

--------------------------------

### Example Next Steps Output

Source: https://docs.edgespark.dev/guides/start-with-template

This example shows the commands emitted after scaffolding a project with specific configurations, including server and web dependencies, environment variables, secrets, database migrations, and authentication.

```text
Next steps:
  cd my-app/server && pnpm install
  cd my-app/web && pnpm install

  edgespark var set LOG_LEVEL=<ask your user>
      request LOG_LEVEL from your user, then run this command
  edgespark var set API_BASE_URL=<ask your user>
      request API_BASE_URL from your user, then run this command

  edgespark secret set STRIPE_KEY
      run this yourself and share only the returned URL with your user

  edgespark db migrate
  edgespark auth apply

  edgespark deploy
      after making your project-specific changes, run dev, test the app, then deploy
```

--------------------------------

### Install Gemini CLI Extension

Source: https://docs.edgespark.dev/agents/supported-agents

Install the EdgeSpark extension for Gemini CLI and initialize a new project.

```bash
gemini extensions install https://github.com/edgesparkhq/gemini-extensions
edgespark init my-app --agent gemini
```

--------------------------------

### AI Agent Prompt for EdgeSpark Project Setup

Source: https://docs.edgespark.dev/guides/start-with-template

This prompt guides an AI coding agent through the entire EdgeSpark project setup flow, from installation to deployment. It includes steps for authentication, initialization, dependency installation, variable and secret management, and applying configurations.

```text
Set up a new EdgeSpark project for me in a directory called `my-app`
from the `bounty-tasks` template.

1. Run `edgespark --version`. If the command is not found, install the CLI
   with `npm install -g @edgespark/cli` and verify it prints a version.
2. Run `edgespark whoami`. If it fails with an auth error, run
   `edgespark login`, print the URL for me to open, and wait for my
   confirmation. The next edgespark command completes the login.
3. Run `edgespark init my-app --agent <YOUR-AGENT-NAME> --template bounty-tasks`.
   Substitute `<YOUR-AGENT-NAME>` with the short identifier of the agent
   you are (`claude` for Claude Code, `codex` for OpenAI Codex, `gemini`
   for Gemini CLI, `cursor` for Cursor, `copilot` for GitHub Copilot, or
   the matching short name for whatever you are). Do not leave the angle
   brackets in the actual command.
4. The "Next steps" block prints one or two
   `cd my-app/<dir> && <pm> install` lines (one for `server/`, and one
   for `web/` if the template has a frontend). Run them in order so
   dependencies are installed before any apply command.
5. Read the rest of the "Next steps" block. For each
   `edgespark var set K=<ask your user>` line, ask me for the value of
   `K` and run the command with the real value (drop the `<ask your
   user>` placeholder). For each `edgespark secret set K` line, run
   the command yourself — it opens a browser URL where I enter the
   secret value; resume when I confirm.
6. Run the remaining `edgespark db migrate`, `edgespark storage apply`,
   and `edgespark auth apply` commands in the order printed, if they
   were emitted.
7. Run `edgespark deploy --dry-run`. If it succeeds, run
   `edgespark deploy`.
```

--------------------------------

### Example Bundle Output

Source: https://docs.edgespark.dev/concepts/deploy-pipeline

Illustrates the compilation output of the application bundle.

```bash
src/index.ts → dist/bundle.js
```

--------------------------------

### Example: Initialize EdgeSpark Project with Claude Agent and Bounty Tasks Template

Source: https://docs.edgespark.dev/guides/start-with-template

This is a concrete example of the `edgespark init` command, specifying 'my-app' as the project name, 'claude' as the agent, and 'bounty-tasks' as the template.

```bash
edgespark init my-app --agent claude --template bounty-tasks
```

--------------------------------

### Example server route

Source: https://docs.edgespark.dev/sdk/overview

An example demonstrating how to use server runtime imports like `db` and `secret`, along with `auth` for user information, within a Hono route.

```APIDOC
## Example server route

```typescript server/src/index.ts theme={null}
import { db, secret } from "edgespark";
import { auth } from "edgespark/http";
import { eq } from "drizzle-orm";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts/:id", async (c) => {
  const stripeKey = secret.get("STRIPE_SECRET_KEY");
  const [post] = await db.select().from(posts).where(eq(posts.id, Number(c.req.param("id"))));

  return c.json({
    post,
    userEmail: auth.user.email,
    hasStripeKey: Boolean(stripeKey),
  });
});

export default app;
```

### Description

This example demonstrates a Hono route that fetches a post by ID, retrieves a secret key, and includes user email and Stripe key status in the response. It utilizes `db` for database queries, `secret` for accessing environment secrets, and `auth` for user session information.
```

--------------------------------

### Route Analyzer Summary Example

Source: https://docs.edgespark.dev/agents/harness

Example output from the route analyzer during 'edgespark deploy', categorizing routes by their authentication convention.

```text
Protected (login required, auth.user guaranteed):   3 routes
  GET    /api/users
  POST   /api/posts
  DELETE /api/posts/:id

Public (login optional, auth.user if logged in):   2 routes
  GET    /api/public/feed
  POST   /api/public/search

Webhooks (no auth check):                          1 routes
  POST   /api/webhooks/stripe
```

--------------------------------

### Install Dependencies

Source: https://docs.edgespark.dev/guides/project-structure

Install Node.js dependencies separately for the server and web components of your project.

```bash
cd server && npm install
cd ../web && npm install
```

--------------------------------

### Install Vitest for testing

Source: https://docs.edgespark.dev/guides/testing

Install Vitest as a development dependency to enable local unit testing for your project.

```bash
npm install -D vitest
```

--------------------------------

### Start the EdgeSpark Dev Server

Source: https://docs.edgespark.dev/guides/local-mode

Run this command from your project root to start the local development server. The app is served at `http://localhost:7775` by default.

```bash
edgespark dev
```

--------------------------------

### Install EdgeSpark Gemini CLI Extension

Source: https://docs.edgespark.dev/agents/gemini-cli

Installs the public Gemini CLI onboarding flow exposed by EdgeSpark.

```bash
gemini extensions install https://github.com/edgesparkhq/gemini-extensions
```

--------------------------------

### Initialize Project and Start Aider

Source: https://docs.edgespark.dev/agents/aider

Initializes a new project with Aider as the agent and starts Aider with the --read flag to provide full EdgeSpark project context. Aider will adhere to EdgeSpark project rules for code generation.

```bash
edgespark init my-app --agent aider
cd my-app
aider --read AGENTS.md src/index.ts
```

--------------------------------

### Install EdgeSpark CLI

Source: https://docs.edgespark.dev/agents/aider

Installs the EdgeSpark CLI globally and logs in the user. Credentials are saved locally for future commands.

```bash
npm install -g @edgespark/cli
edgespark login
```

--------------------------------

### Install OpenAI Codex Plugin

Source: https://docs.edgespark.dev/agents/supported-agents

Install the EdgeSpark Codex plugin for OpenAI Codex and initialize a new project.

```bash
codex
# Then paste the EdgeSpark Codex plugin install prompt from the Codex setup page
edgespark init my-app --agent codex
```

--------------------------------

### Successful Deployment Output

Source: https://docs.edgespark.dev/guides/deployment

Example output indicating a successful build and deployment, showing the final URL. This confirms the deployment process completed without errors.

```text
✓ Schema synced
✓ Built in 1.4s
✓ Deployed

https://my-app.edgespark.app
```

--------------------------------

### Install Claude Code Plugin

Source: https://docs.edgespark.dev/agents/supported-agents

Install the EdgeSpark plugin for Claude Code and initialize a new project.

```bash
claude plugin marketplace add edgesparkhq/claude-plugins
claude plugin install edgespark@edgespark-claude-plugins
edgespark init my-app --agent claude
```

--------------------------------

### Install EdgeSpark GitHub Copilot Plugin

Source: https://docs.edgespark.dev/agents/github-copilot

Adds the EdgeSpark Copilot plugin from the marketplace and installs it. This follows the public GitHub Copilot onboarding flow.

```bash
copilot plugin marketplace add edgesparkhq/copilot-plugins
copilot plugin install edgespark@edgespark-copilot-plugins
```

--------------------------------

### Get Command Help

Source: https://docs.edgespark.dev/cli/installation

Displays help information for CLI commands, including options and usage details.

```bash
edgespark --help
edgespark deploy --help
edgespark secret --help
```

--------------------------------

### Install Project Dependencies

Source: https://docs.edgespark.dev/cli/installation

Installs npm dependencies separately for the server and web directories within the scaffolded project.

```bash
cd my-app/server && npm install
cd ../web && npm install
```

--------------------------------

### Initialize EdgeSpark Project with Claude Agent

Source: https://docs.edgespark.dev/agents/agents-md

Example of initializing a new EdgeSpark project and specifying the 'claude' agent, which results in the generation of a CLAUDE.md file.

```bash
edgespark init my-app --agent claude
# Writes CLAUDE.md to my-app/
```

--------------------------------

### Server Route Example

Source: https://docs.edgespark.dev/sdk/overview

An example of a Hono server route that fetches a post from the database using its ID, retrieves a secret, and includes user authentication information.

```typescript
import { db, secret } from "edgespark";
import { auth } from "edgespark/http";
import { eq } from "drizzle-orm";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts/:id", async (c) => {
  const stripeKey = secret.get("STRIPE_SECRET_KEY");
  const [post] = await db.select().from(posts).where(eq(posts.id, Number(c.req.param("id"))));

  return c.json({
    post,
    userEmail: auth.user.email,
    hasStripeKey: Boolean(stripeKey),
  });
});

export default app;
```

--------------------------------

### Install EdgeSpark CLI

Source: https://docs.edgespark.dev/cli/installation

Installs the EdgeSpark CLI globally using npm. This command is the first step to using the EdgeSpark command-line tools.

```bash
npm install -g @edgespark/cli
```

--------------------------------

### Install EdgeSpark Skills and MCP

Source: https://docs.edgespark.dev/agents/supported-agents

Install EdgeSpark agent skills and the Message Communication Protocol (MCP) for various agents.

```bash
npx skills add edgesparkhq/agent-skills
npx add-mcp https://mcp.edgespark.dev/docs
```

--------------------------------

### Install EdgeSpark Claude Code Plugin

Source: https://docs.edgespark.dev/agents/claude-code

Adds the EdgeSpark plugin marketplace and installs the specific EdgeSpark plugin for Claude Code.

```bash
claude plugin marketplace add edgesparkhq/claude-plugins
claude plugin install edgespark@edgespark-claude-plugins
```

--------------------------------

### Example API Handler with Typed Imports

Source: https://docs.edgespark.dev/agents/declarative-workflow

This TypeScript example demonstrates how to write an API handler using generated SDK types for database access. Ensure you have the necessary imports from 'edgespark' and your defined schema.

```typescript
import { db } from "edgespark";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts", async (c) => {
  return c.json(await db.select().from(posts));
});

export default app;
```

--------------------------------

### Example EdgeSpark Auth Configuration

Source: https://docs.edgespark.dev/guides/auth-config

This YAML file demonstrates the structure for configuring sign-up policies, session settings, email/password authentication, and OAuth providers like Google and GitHub.

```yaml
# yaml-language-server: $schema=https://schemas.edgespark.dev/v1/auth-config.schema.json

disableSignUp: false

session:
  expiresIn: 604800
  updateAge: 86400
  disableSessionRefresh: false

providerEmailPassword:
  enabled: true
  config:
    minPasswordLength: 10
    requireEmailVerification: true
    requirePasswordResetEmailVerification: true
    revokeSessionsOnPasswordReset: true

providerGoogle:
  enabled: true
  config:
    clientIdVarRef: GOOGLE_CLIENT_ID
    clientSecretRef: GOOGLE_CLIENT_SECRET

providerGithub:
  enabled: true
  config:
    clientIdVarRef: GITHUB_CLIENT_ID
    clientSecretRef: GITHUB_CLIENT_SECRET
```

--------------------------------

### Upload and Download Files

Source: https://docs.edgespark.dev/sdk/storage

Upload a file to a bucket using `put` and retrieve it using `get`. Ensure the object exists before processing.

```typescript
import { storage } from "edgespark";
import { buckets } from "@defs";

await storage
  .from(buckets.uploads)
  .put("reports/q1.pdf", new TextEncoder().encode("report"));

const object = await storage.from(buckets.uploads).get("reports/q1.pdf");
if (!object) throw new Error("Not found");
```

--------------------------------

### Enable Multiple Social Providers

Source: https://docs.edgespark.dev/guides/social-login

Configure multiple social login providers (Google, GitHub, Discord) in your `configs/auth-config.yaml` file. This example also enables email/password authentication.

```yaml
# yaml-language-server: $schema=https://schemas.edgespark.dev/v1/auth-config.schema.json

disableSignUp: false

providerEmailPassword:
  enabled: true
  config:
    minPasswordLength: 10
    requireEmailVerification: true

providerGoogle:
  enabled: true
  config:
    clientIdVarRef: GOOGLE_CLIENT_ID
    clientSecretRef: GOOGLE_CLIENT_SECRET

providerGithub:
  enabled: true
  config:
    clientIdVarRef: GITHUB_CLIENT_ID
    clientSecretRef: GITHUB_CLIENT_SECRET

providerDiscord:
  enabled: true
  config:
    clientIdVarRef: DISCORD_CLIENT_ID
    clientSecretRef: DISCORD_CLIENT_SECRET
```

--------------------------------

### Install and Use EdgeSpark Copilot Plugin

Source: https://docs.edgespark.dev/agents/supported-agents

Add the EdgeSpark Copilot plugin to GitHub Copilot and initialize an EdgeSpark app. This enables EdgeSpark tasks within Copilot.

```bash
copilot plugin marketplace add edgesparkhq/copilot-plugins
```

```bash
copilot plugin install edgespark@edgespark-copilot-plugins
```

```bash
edgespark init my-app --agent copilot
```

--------------------------------

### Import Storage and Define Bucket

Source: https://docs.edgespark.dev/sdk/storage

Import the storage module and define bucket references from @defs. This is a common setup for using storage operations.

```typescript
import { storage } from "edgespark";
import { buckets } from "@defs";

const uploads = storage.from(buckets.uploads);
```

--------------------------------

### Basic Runtime Handler with SDK Imports

Source: https://docs.edgespark.dev/concepts/client-object

This example demonstrates a typical Hono route handler that imports and uses SDK values from `edgespark` and `edgespark/http` to interact with the database and authentication services.

```typescript
import { db } from "edgespark";
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts", async (c) => {
  const rows = await db.select().from(posts);

  return c.json({
    posts: rows,
    userEmail: auth.user.email,
  });
});

export default app;
```

--------------------------------

### DNS records for custom domain

Source: https://docs.edgespark.dev/guides/custom-domains

Example of DNS records (CNAME and TXT) provided by the CLI after adding a domain. These are required for routing and ownership verification.

```text
Domain added

Hostname: app.example.com
Status:   pending

DNS records
  CNAME  app.example.com -> custom.edgespark.app
        Purpose: routing
  TXT    _edgespark-verify-<scoped>.app.example.com -> edgespark-domain-verification=<token>
        Purpose: ownership

User action required
  1. Add every DNS record above at the domain's DNS provider.
     For apex/root domains, use @ if your DNS provider asks for a host/name.
  2. Wait for DNS propagation; EdgeSpark certificate issuance is automatic.
  3. Run `edgespark domain verify app.example.com` to wait for activation.
```

--------------------------------

### Start Dev Server on a Different Port

Source: https://docs.edgespark.dev/guides/local-mode

Specify a different port for the local development server using the `--port` flag. This is useful if the default port is already in use.

```bash
edgespark dev --port 8080
```

--------------------------------

### Accessing Storage Bucket Objects

Source: https://docs.edgespark.dev/concepts/client-object

Interact with your project's R2 storage buckets using the `storage` object. This example shows how to retrieve a specific object from a bucket.

```typescript
const object = await storage.from(buckets.uploads).get("docs/report.pdf");
```

--------------------------------

### Hono API with EdgeSpark Runtime SDK

Source: https://docs.edgespark.dev/index

Example of a Hono application using the EdgeSpark runtime SDK for database access and authentication. No explicit setup for database credentials, storage clients, or auth middleware is needed in the app code.

```typescript
import { db } from "edgespark";
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts", async (c) => {
  const rows = await db.select().from(posts);
  return c.json({ posts: rows, userEmail: auth.user.email });
});

export default app;
```

--------------------------------

### Initialize Project and Configure Windsurf

Source: https://docs.edgespark.dev/agents/windsurf

Initializes a new project for Windsurf and copies the AGENTS.md file to .windsurfrules to provide project context.

```bash
edgespark init my-app --agent windsurf
cd my-app
cp AGENTS.md .windsurfrules
```

--------------------------------

### Verify CLI Installation

Source: https://docs.edgespark.dev/cli/installation

Checks the installed version of the EdgeSpark CLI to confirm successful installation.

```bash
edgespark --version
```

--------------------------------

### Test deployed API with fetch script

Source: https://docs.edgespark.dev/guides/testing

Automate integration tests using a TypeScript `fetch` script. This example creates a post and then reads it back, asserting the expected status codes and data.

```typescript
const BASE = "https://my-app.edgespark.app";
const SESSION = process.env.SESSION_TOKEN!;

const headers = {
  Cookie: `better-auth.session_token=${SESSION}`,
  "Content-Type": "application/json",
};

// Create a post
const createRes = await fetch(`${BASE}/api/posts`, {
  method: "POST",
  headers,
  body: JSON.stringify({ title: "Test post" }),
});
const post = await createRes.json();
console.assert(createRes.status === 201, "Expected 201");
console.assert(post.title === "Test post", "Expected title");

// Read it back
const getRes = await fetch(`${BASE}/api/posts/${post.id}`, { headers });
const fetched = await getRes.json();
console.assert(getRes.status === 200, "Expected 200");
console.assert(fetched.id === post.id, "Expected same ID");

console.log("All assertions passed");
```

--------------------------------

### Initialize Project from HTTPS URL

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project from a template hosted at a full HTTPS URL.

```bash
edgespark init my-app --agent claude -t https://github.com/acme/starter
```

--------------------------------

### Initialize Project from Local Directory

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project using a template located in a local directory, specified by a relative or absolute path.

```bash
edgespark init my-app --agent claude -t ./my-template
```

--------------------------------

### Initialize Project from Tarball URL

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project from a template provided as a raw tarball URL.

```bash
edgespark init my-app --agent claude -t https://example.com/template.tar.gz
```

--------------------------------

### Initialize Project from SSH URL

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project from a template hosted on a Git server accessible via SSH.

```bash
edgespark init my-app --agent claude -t git@github.com:acme/starter.git
```

--------------------------------

### Initialize Project from GitHub Repository

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project from a GitHub repository using the 'github:' shorthand. You can specify a subdirectory and a tag or branch.

```bash
edgespark init my-app --agent claude -t github:acme/starter
```

```bash
edgespark init my-app --agent claude -t github:acme/starter/subdir
```

```bash
edgespark init my-app --agent claude -t github:acme/starter#v1.0.0
```

--------------------------------

### Initialize Project and Configure Continue

Source: https://docs.edgespark.dev/agents/continue

Initializes a new project with the EdgeSpark CLI for Continue and configures the Continue extension to reference AGENTS.md for project context.

```bash
edgespark init my-app --agent continue
cd my-app
```

```yaml
context:
  - provider: file
    params:
      filepath: ./AGENTS.md
```

--------------------------------

### Add a custom domain

Source: https://docs.edgespark.dev/guides/custom-domains

Registers a hostname against your project and prints the necessary DNS records for configuration. Copy these records verbatim from the CLI output.

```bash
edgespark domain add app.example.com
```

--------------------------------

### Initialize Project with Official Template

Source: https://docs.edgespark.dev/guides/start-with-template

Use this command to initialize a new project from an official Edgespark template like 'fullstack'. Specify the agent to use.

```bash
edgespark init my-app --agent claude -t fullstack
```

--------------------------------

### Initialize Project with Specific Branch

Source: https://docs.edgespark.dev/guides/start-with-template

Initialize a project from a specific branch (e.g., 'main') of an official template.

```bash
edgespark init my-app --agent claude -t bounty-tasks#main
```

--------------------------------

### Deploy project

Source: https://docs.edgespark.dev/cli/commands

Build and deploy your project to its default environment. A dry-run option is available to validate the deployment before it occurs.

```bash
edgespark deploy
```

```bash
edgespark deploy --dry-run
```

--------------------------------

### TypeScript Compile-Time Type Error Example

Source: https://docs.edgespark.dev/agents/harness

An example of a TypeScript error caught by the compiler during deployment, indicating a property does not exist on a type, preventing type-incorrect code from being deployed.

```typescript
error TS2339: Property 'bio' does not exist on type 'typeof tables.users'
```

--------------------------------

### Initialize Storage

Source: https://docs.edgespark.dev/sdk/storage

Import the storage module and initialize it with a bucket declaration.

```APIDOC
## Initialize Storage

Use the `storage.from(bucket)` method to get a reference to a specific bucket.

### Method

```typescript
storage.from(bucket: BucketDeclaration)
```

### Parameters

#### Path Parameters

- **bucket** (BucketDeclaration) - Required - The bucket to interact with, typically imported from `@defs`.

### Request Example

```typescript
import { storage } from "edgespark";
import { buckets } from "@defs";

const uploads = storage.from(buckets.uploads);
```
```

--------------------------------

### Initialize Project and Configure Cline

Source: https://docs.edgespark.dev/agents/cline

Initializes a new EdgeSpark project named 'my-app' with the 'cline' agent and copies the AGENTS.md file to .clinerules for Cline's context.

```bash
edgespark init my-app --agent cline
cd my-app
cp AGENTS.md .clinerules
```

--------------------------------

### Install EdgeSpark Codex Plugin Prompt

Source: https://docs.edgespark.dev/agents/codex

A detailed prompt to be pasted into Codex for installing or updating the EdgeSpark Codex plugin. It specifies the release zip, extraction, and file placement instructions, including merging the plugin entry into marketplace.json.

```text
$plugin-creator Install or update the EdgeSpark Codex plugin
from this exact release zip:
https://github.com/edgesparkhq/codex-plugins/releases/latest/download/edgespark-codex-plugins.zip
Extract that zip and use its bundled files directly.
Copy plugins/edgespark/ into ~/.codex/plugins/edgespark/.
Use the bundled .agents/plugins/marketplace.json as the source of truth:
- If ~/.agents/plugins/marketplace.json does not exist, copy the bundled file there.
- If it already exists, merge only the edgespark plugin entry from the bundled file.
- Preserve unrelated existing plugin entries.
- Preserve existing top-level marketplace metadata, including name and interface.displayName.
Do not invent a different install layout or rewrite the EdgeSpark plugin entry to another path.
Tell me when the local plugin files are updated.
```

--------------------------------

### Scaffold a New Project

Source: https://docs.edgespark.dev/cli/installation

Initializes a new full-stack project with a specified agent (e.g., codex). This creates a standard project structure.

```bash
edgespark init my-app --agent codex
```

--------------------------------

### Pull and Inspect Auth Configuration

Source: https://docs.edgespark.dev/guides/auth-config

Use these commands to fetch the current live authentication configuration and view it.

```bash
edgespark auth pull
edgespark auth get
```

--------------------------------

### Initialize Project with Agent

Source: https://docs.edgespark.dev/agents/other-agents

Generate the AGENTS.md file for your project by initializing EdgeSpark with your agent's name. This file serves as the primary instructions for many agents.

```bash
edgespark init my-app --agent your-agent-name
# Examples: opencode, amp, devin, aider,
# windsurf, cline, continue, antigravity, kiro,
# or your own custom agent name
# These all write AGENTS.md today.
```

--------------------------------

### Start EdgeSpark Task in Codex

Source: https://docs.edgespark.dev/agents/codex

Executes a specific EdgeSpark task within Codex, identified by the task-entry command.

```text
$edgespark:building-edgespark-apps
```

--------------------------------

### Get Applied Auth Configuration in JSON

Source: https://docs.edgespark.dev/guides/auth-config

Retrieve the current applied authentication configuration in a machine-readable JSON format.

```bash
edgespark auth get --json
```

--------------------------------

### Deploy and Tail Logs

Source: https://docs.edgespark.dev/guides/development-workflow

Standard commands for deploying updates and tailing logs during development.

```bash
edgespark deploy
edgespark log tail
```

--------------------------------

### Initialize an EdgeSpark Project with a Template

Source: https://docs.edgespark.dev/guides/start-with-template

Use this command to create a new project from a specified template and agent. Substitute placeholders for your project name, agent identifier, and template source.

```bash
edgespark init <project-name> --agent <agent> --template <template>
```

--------------------------------

### Add a custom domain

Source: https://docs.edgespark.dev/cli/commands

Register a hostname against the current project. This command will print the necessary DNS records that need to be published to make the domain active.

```bash
edgespark domain add <hostname>
```

--------------------------------

### Retrieving Authenticated User Email

Source: https://docs.edgespark.dev/concepts/client-object

Access the `auth` object from `edgespark/http` to get details about the currently authenticated user, such as their email address.

```typescript
const email = auth.user.email;
```

--------------------------------

### Start EdgeSpark Task in Cursor

Source: https://docs.edgespark.dev/agents/cursor

Initiates an EdgeSpark task within the Cursor Agent chat using the plugin command and a descriptive prompt.

```text
/building-edgespark-apps
Build a full-stack EdgeSpark app with auth and storage.
```

--------------------------------

### Initialize EdgeSpark Project for Amp

Source: https://docs.edgespark.dev/agents/amp

Initializes a new EdgeSpark project named 'my-app' with Amp as the target agent and navigates into the project directory. The AGENTS.md file is kept as the primary instructions file for Amp.

```bash
edgespark init my-app --agent amp
cd my-app
```

--------------------------------

### Initialize EdgeSpark Project for Devin

Source: https://docs.edgespark.dev/agents/devin

Initializes a new EdgeSpark project named 'my-app' configured for the Devin agent and navigates into the project directory.

```bash
edgespark init my-app --agent devin
cd my-app
```

--------------------------------

### Define Local Database Seed Script

Source: https://docs.edgespark.dev/guides/local-mode

Create a `server/dev/seed.ts` file to seed your local database. This script runs automatically when `edgespark dev` starts.

```typescript
import { defineSeed } from "@edgespark/devkit";
import type { SqliteRemoteDatabase } from "drizzle-orm/sqlite-proxy";
import { posts } from "../src/defs/db_schema";
import type * as schema from "../src/defs/db_schema";

export default defineSeed<SqliteRemoteDatabase<typeof schema>>(async (ctx) => {
  const { user, fetch } = await ctx.auth.createUser({
    email: "alice@example.com",
    password: "correct-horse-battery-staple",
    name: "Alice",
  });

  await ctx.db.insert(posts).values([
    { title: "Hello world", authorId: user.id },
    { title: "Second post", authorId: user.id },
  ]);

  const response = await fetch("/api/posts");
  console.log(`Seeded ${user.email} with ${(await response.json()).length} posts`);
});
```

--------------------------------

### Open Drizzle Studio

Source: https://docs.edgespark.dev/cli/commands

Opens Drizzle Studio against the project database. You can specify a custom port or host to bind to.

```bash
edgespark db studio
```

```bash
edgespark db studio --port <port>
```

```bash
edgespark db studio --host <host>
```

--------------------------------

### Public Route Example

Source: https://docs.edgespark.dev/concepts/path-based-auth

This snippet shows a public route under /api/public/*. It fetches posts and optionally includes the current user's ID if logged in.

```typescript
import { db } from "edgespark";
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/public/posts", async (c) => {
  const rows = await db.select().from(posts);

  if (auth.user) {
    return c.json({ posts: rows, currentUserId: auth.user.id });
  }

  return c.json({ posts: rows });
});

export default app;
```

--------------------------------

### Initialize EdgeSpark Project with Gemini Agent

Source: https://docs.edgespark.dev/agents/gemini-cli

Initializes a new project named 'my-app' and generates a GEMINI.md file at the project root for Gemini CLI sessions.

```bash
edgespark init my-app --agent gemini
cd my-app
```

--------------------------------

### Protected Route Example

Source: https://docs.edgespark.dev/concepts/path-based-auth

This snippet demonstrates a protected route under /api/*. It accesses user information via `auth.user` for profile retrieval and post creation.

```typescript
import { db } from "edgespark";
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono()
  .get("/api/profile", (c) => {
    return c.json({ email: auth.user.email, id: auth.user.id });
  })
  .post("/api/posts", async (c) => {
    const body = await c.req.json<{ title: string }>();

    await db.insert(posts).values({
      title: body.title,
      authorId: auth.user.id,
    });

    return c.json({ created: true }, 201);
  });

export default app;
```

--------------------------------

### Using Request-Scoped Context Helpers

Source: https://docs.edgespark.dev/concepts/client-object

The `ctx` object provides request-scoped helpers. This example shows how to run a function in the background and check the current environment.

```typescript
ctx.runInBackground(sendAnalyticsEvent());

if (ctx.environment === "production") {
  // Production-only behavior
}
```

--------------------------------

### Initialize EdgeSpark Project for OpenCode

Source: https://docs.edgespark.dev/agents/opencode

Initializes a new EdgeSpark project named 'my-app' with OpenCode as the agent and navigates into the project directory. The `AGENTS.md` file is kept as the primary instruction file.

```bash
edgespark init my-app --agent opencode
cd my-app
```

--------------------------------

### Retrieving Encrypted Secrets

Source: https://docs.edgespark.dev/concepts/client-object

Use the `secret` object to securely access encrypted secrets configured for your project. This example retrieves a Stripe API key.

```typescript
const apiKey = secret.get("STRIPE_SECRET_KEY");
```

--------------------------------

### Initialize EdgeSpark Project for Cursor

Source: https://docs.edgespark.dev/agents/cursor

Initializes a new EdgeSpark project scaffolded for Cursor. This creates the AGENTS.md file used by EdgeSpark as project instructions.

```bash
edgespark init my-app --agent cursor
cd my-app
```

--------------------------------

### Reading Plain Environment Variables

Source: https://docs.edgespark.dev/concepts/client-object

Access non-sensitive runtime configuration values using the `vars` object. This example retrieves a public API base URL.

```typescript
const apiBaseUrl = vars.get("PUBLIC_API_BASE_URL");
```

--------------------------------

### Useful Database CLI Commands

Source: https://docs.edgespark.dev/guides/database

Explore additional CLI commands for managing your database, including generating migrations with a specific name, checking schema status, and accessing the database studio.

```bash
edgespark db generate --name add_posts
edgespark db check
edgespark db studio
```

--------------------------------

### Add EdgeSpark Agent Skills

Source: https://docs.edgespark.dev/agents/aider

Installs the generic EdgeSpark skills package for various AI coding agents. This is used when an agent lacks a dedicated EdgeSpark plugin.

```bash
npx skills add edgesparkhq/agent-skills
```

--------------------------------

### Start EdgeSpark Task in GitHub Copilot

Source: https://docs.edgespark.dev/agents/github-copilot

Command to initiate an EdgeSpark task within GitHub Copilot. This command is used to trigger specific workflows defined in AGENTS.md.

```text
/edgespark:building-edgespark-apps
```

--------------------------------

### Set up Generic EdgeSpark Agent Skills and MCP

Source: https://docs.edgespark.dev/agents/supported-agents

Add EdgeSpark agent skills and the documentation MCP path for use with generic AI agents. This is a prerequisite for initializing apps with agents that do not have dedicated plugins.

```bash
npx skills add edgesparkhq/agent-skills
```

```bash
npx add-mcp https://mcp.edgespark.dev/docs
```

```bash
edgespark init my-app --agent your-agent-name
```

--------------------------------

### Context (ctx) Usage Example

Source: https://docs.edgespark.dev/sdk/overview

Demonstrates using `ctx.runInBackground` to execute a function asynchronously without blocking the main request-response cycle, and accessing the environment via `ctx.environment`.

```typescript
import { ctx } from "edgespark";
import { Hono } from "hono";

async function sendToAnalytics(event: unknown) {
  await fetch("https://example.com/analytics", {
    method: "POST",
    body: JSON.stringify(event),
  });
}

const app = new Hono().post("/api/events", async (c) => {
  const event = await c.req.json();

  ctx.runInBackground(sendToAnalytics(event));

  return c.json({
    received: true,
    environment: ctx.environment,
  });
});

export default app;
```

--------------------------------

### Scaffold a Local-Only Project

Source: https://docs.edgespark.dev/cli/installation

Initializes a new project locally without creating a remote project yet, using a specified agent.

```bash
edgespark init my-app --agent codex --scaffold
```

--------------------------------

### Initialize a new EdgeSpark project

Source: https://docs.edgespark.dev/cli/commands

Create a new EdgeSpark project with a specified name and agent. The agent name determines the type of instructions file generated. You can also initialize from a template using various source formats.

```bash
edgespark init <name> --agent <name>
```

```bash
edgespark init <name> --agent <name> -t <src>
```

--------------------------------

### Extend AGENTS.md with Project-Specific Rules

Source: https://docs.edgespark.dev/agents/github-copilot

Example of adding custom rules to the AGENTS.md file below the generated content. These rules are prioritized by GitHub Copilot alongside the generated instructions.

```markdown
<!-- Generated content above — do not edit -->

## Project-specific rules

- The `posts` table is soft-deleted — always filter `WHERE deleted_at IS NULL`
- Route `/api/admin/*` requires `user.role === 'admin'` checked after platform auth
```

--------------------------------

### Server Entry Point

Source: https://docs.edgespark.dev/guides/project-structure

The main Hono application for the server, setting up API routes for authentication, posts, and users.

```typescript
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { postsRoutes } from "./routes/posts";
import { usersRoutes } from "./routes/users";

const app = new Hono()
  .get("/api/me", (c) => c.json({ email: auth.user.email }));

app.route("/api/posts", postsRoutes);
app.route("/api/users", usersRoutes);

export default app;
```
Tokens:
Raw