CLI Reference

Complete reference for the Confect CLI tool for development and code generation

The Confect CLI (@confect/cli) provides commands for generating code, running development servers, and managing your Confect project.

Overview

confect dev

Start the development server with hot reloading

confect codegen

Generate type-safe API code from your spec

Installation

Install the CLI globally or use it via your package manager:

# Using npm
npm install -g @confect/cli

# Using pnpm
pnpm add -g @confect/cli

# Or use via package.json scripts
npm install --save-dev @confect/cli

confect dev

Start the development server with automatic code generation and hot reloading.

Usage

confect dev

What it Does

Watch Files

Monitors your spec files for changes

Generate Code

Automatically generates API and refs

Sync Functions

Updates Convex function files

Hot Reload

Instant updates without restart

Example Output

$ confect dev
⏳ Performing initial sync…
+ confect/_generated/api.ts
+ confect/_generated/refs.ts
+ confect/_generated/services.ts
+ confect/_generated/registeredFunctions.ts
+ convex/schema.ts
+ convex/users.ts
  + users.list
  + users.getById
  + users.create
+ convex/posts.ts
  + posts.list
  + posts.create
  + posts.update
✓ Generated files are up-to-date

Watching for changes...

File Watching

The dev command watches these directories:

confect/spec.ts

Your main Confect specification

confect/nodeSpec.ts

Node.js-specific functions (optional)

confect/nodeImpl.ts

Node.js implementations (optional)

confect/http.ts

HTTP routes (optional)

confect/crons.ts

Scheduled functions (optional)

confect/auth.ts

Auth configuration (optional)

Change Detection

When you modify files, the CLI automatically:

# After editing spec.ts
⏳ Dependencies changed, reloading…
~ confect/_generated/api.ts
~ convex/users.ts
  + users.update
✓ Generated files are up-to-date

Error Handling

The dev server shows detailed error messages with file locations and suggestions for fixes.

# Build error example
✗ Build errors found

error: Could not resolve "./nonexistent"
    confect/spec.ts:3:24:
      3 │ import { users } from "./nonexistent";
                                ~~~~~~~~~~~~~~~~

✗ Spec import failed

confect codegen

Generate all code files without starting the dev server.

Usage

confect codegen

What it Does

packages/cli/src/confect/codegen.ts

$ confect codegen
⏳ Performing initial sync…
+ confect/_generated/
+ confect/_generated/api.ts
+ confect/_generated/refs.ts
+ confect/_generated/services.ts
+ confect/_generated/registeredFunctions.ts
+ confect/_generated/nodeApi.ts
+ confect/_generated/nodeRegisteredFunctions.ts
+ convex/schema.ts
+ convex/users.ts
+ convex/posts.ts
+ convex/http.ts
+ convex/crons.ts
+ convex/auth.config.ts
✓ Generated files are up-to-date

Generated Files

The codegen command creates these files:

confect/_generated/api.ts

Type-safe API client for server-side usage:

import { Api } from "@confect/server";
import databaseSchema from "../schema";
import spec from "../spec";

export const api = Api.make(databaseSchema, spec);

confect/_generated/refs.ts

Type-safe references for all functions:

import { Refs } from "@confect/core";
import spec from "../spec";
import nodeSpec from "../nodeSpec";

export const refs = Refs.make(spec, nodeSpec);

confect/_generated/services.ts

Effect services for database operations:

export { DatabaseReader, DatabaseWriter } from "@confect/server";
// ... other services

confect/_generated/registeredFunctions.ts

Convex-compatible function exports:

import { RegisteredFunctions } from "@confect/server";
import impl from "../impl";

export default RegisteredFunctions.make(impl);

convex/schema.ts

Generated Convex schema:

import schema from "../confect/schema";
export default schema.convexSchemaDefinition;

convex/*.ts (Function Files)

Generated function modules:

// convex/users.ts
import registeredFunctions from "../confect/_generated/registeredFunctions";

export const list = registeredFunctions.users.list;
export const getById = registeredFunctions.users.getById;
export const create = registeredFunctions.users.create;

Use Cases

CI/CD

Run codegen in your build pipeline

Pre-commit

Generate code before committing

Testing

Ensure generated code is up-to-date

Deployment

Generate production code

Package.json Scripts

{
  "scripts": {
    "dev": "confect dev",
    "codegen": "confect codegen",
    "build": "confect codegen && convex deploy",
    "precommit": "confect codegen && git add convex/ confect/_generated/"
  }
}

Project Structure

The CLI expects this directory structure:

project/
├── confect/
│   ├── spec.ts              # Main specification
│   ├── schema.ts            # Database schema
│   ├── impl.ts              # Function implementations
│   ├── nodeSpec.ts          # (Optional) Node.js spec
│   ├── nodeImpl.ts          # (Optional) Node.js implementations
│   ├── http.ts              # (Optional) HTTP routes
│   ├── crons.ts             # (Optional) Scheduled functions
│   ├── auth.ts              # (Optional) Auth config
│   └── _generated/          # Generated by CLI
│       ├── api.ts
│       ├── refs.ts
│       ├── services.ts
│       ├── registeredFunctions.ts
│       ├── nodeApi.ts
│       └── nodeRegisteredFunctions.ts
├── convex/                   # Generated by CLI
│   ├── schema.ts
│   ├── users.ts
│   ├── posts.ts
│   ├── http.ts
│   ├── crons.ts
│   └── auth.config.ts
└── package.json

Configuration

Directory Customization

The CLI uses these default directories:

Confect Directory

./confect - Your source files

Convex Directory

./convex - Generated Convex files

These can be customized via environment variables:

CONFECT_DIR=./src/confect confect dev
CONVEX_DIR=./build/convex confect dev

Advanced Usage

Debugging

Enable debug logging:

DEBUG=confect:* confect dev

Node.js Actions

Create Node.js-specific actions:

// confect/nodeSpec.ts
import { Spec, GroupSpec, FunctionSpec } from "@confect/core";
import { Schema } from "effect";

const files = GroupSpec.makeNode("files")
  .addFunction(
    FunctionSpec.publicNodeAction({
      name: "process",
      args: Schema.Struct({
        filePath: Schema.String
      }),
      returns: Schema.Struct({
        success: Schema.Boolean
      })
    })
  );

const nodeSpec = Spec.makeNode().add(files);

export default nodeSpec;

HTTP Routes

Define HTTP endpoints:

// confect/http.ts
import { httpRouter } from "convex/server";

const http = httpRouter();

http.route({
  path: "/webhook",
  method: "POST",
  handler: async (request) => {
    const data = await request.json();
    // Process webhook
    return new Response(null, { status: 200 });
  }
});

export default http;

Scheduled Functions

Define cron jobs:

// confect/crons.ts
import { cronJobs } from "convex/server";
import { refs } from "./_generated/refs";

const crons = cronJobs();

crons.interval(
  "cleanup",
  { hours: 24 },
  refs.internal.maintenance.cleanup
);

crons.cron(
  "daily-report",
  "0 9 * * *", // 9 AM daily
  refs.internal.reports.generate
);

export default crons;

Troubleshooting

Spec Import Failed

Check for syntax errors in spec.ts

Invalid Schema

Ensure schema.ts exports valid schema

Build Errors

Review error messages and file locations

Port Conflicts

Ensure no other process is using ports

Common Issues

Spec File Doesn’t Export Spec

✗ Spec file does not default export a Convex spec

Solution: Ensure your spec.ts has a default export:

// ✅ Correct
export default Spec.make().add(users);

// ❌ Wrong
export const spec = Spec.make().add(users);

Missing Dependencies

error: Could not resolve "effect"

Solution: Install required dependencies:

npm install effect @confect/core @confect/server

Environment Variables

CONFECT_DIR · string · default: "./confect"

Directory containing your Confect source files

CONVEX_DIR · string · default: "./convex"

Directory for generated Convex files

DEBUG · string · default: ""

Enable debug logging (e.g., DEBUG=confect:*)

Next Steps

Core API

Learn about Confect core types

Server API

Implement backend functions

React Hooks

Use Confect in React apps

Testing

Test your Confect application