CLI Concepts

Agent-First Development

Corsair's CLI is designed for coding agents to interact with your project directly.

Whatever coding agent you use—Claude, Cursor, Windsurf, or any other—can create and modify queries and mutations through simple CLI commands.

pnpm corsair query -n "get posts with authors" -i "fetch all posts with author details from posts and users tables"

The result: You get the speed of coding agents with the reliability of a senior engineer who sat down and coded everything from scratch.

Creating Queries

Agents can create fully typed queries with a single command.

Basic Query

pnpm corsair query \
  -n "get posts with authors" \
  -i "fetch all posts with author details from posts and users tables"

Query with Parameters

pnpm corsair query \
  -n "get comments by post id" \
  -i "get all comments for a specific post ID including author information"

Complex Aggregations

pnpm corsair query \
  -n "get user profile" \
  -i "fetch user profile with their posts count and recent activity"

What happens:

The agent runs the command
Corsair generates the fully typed implementation
The query is immediately available in your codebase
TypeScript types are automatically exported

Creating Mutations

Mutations work the same way—one command, fully typed implementation.

Create Operations

pnpm corsair mutation \
  -n "create post" \
  -i "create a new post with title, content, and author ID"

Update Operations

pnpm corsair mutation \
  -n "update comment" \
  -i "update an existing comment's content by comment ID"

Delete Operations

pnpm corsair mutation \
  -n "delete post" \
  -i "delete a post and all its associated comments by post ID"

Multi-Service Mutations

pnpm corsair mutation \
  -n "create order and notify" \
  -i "create order in database and send slack notification about order details"

Updating Existing Queries and Mutations

Need to modify an existing query? Use the -u (update) flag.

pnpm corsair query \
  -n "get posts with authors" \
  -i "fetch all published posts with author details, sorted by created date" \
  -u

What this does:

Finds the existing query by name
Regenerates it with the new instructions
Updates the implementation and types
Preserves the query name so existing code continues to work

Why This Matters for Agents

Reduced Context Bloat

Instead of an agent generating an entire database query inline:

// Agent generates 50+ lines of Prisma code
const posts = await prisma.post.findMany({
  where: { published: true },
  include: {
    author: {
      select: { id: true, name: true, email: true },
    },
    comments: {
      where: { approved: true },
      include: { author: true },
    },
  },
  orderBy: { createdAt: 'desc' },
})

The agent simply runs:

pnpm corsair query -n "get published posts with approved comments" -i "fetch all published posts with their approved comments and author details"

Benefits:

Minimal token usage — one CLI command instead of pages of generated code
No context bloat — the agent delegates to Corsair instead of holding implementation details
Type safety — Corsair handles the types, not the agent
Less technical debt — vetted, consistent code generation

The Agent Workflow

Here's how a coding agent uses Corsair in practice:

1. User Request

"Build a feature to display user profiles with their recent posts"

2. Agent Creates Query

pnpm corsair query \
  -n "get user profile with recent posts" \
  -i "fetch user by ID with their 10 most recent posts including title and created date"

3. Agent Uses the Query

// Agent writes minimal code using the generated query
export function UserProfile({ userId }: { userId: string }) {
  const { data: user } = useCorsairQuery('get user profile with recent posts', {
    userId,
  })

  return (
    <div>
      <h1>{user?.name}</h1>
      <PostList posts={user?.recentPosts} />
    </div>
  )
}

4. User Requests Changes

"Actually, show 20 posts and include the post content too"

5. Agent Updates Query

pnpm corsair query \
  -n "get user profile with recent posts" \
  -i "fetch user by ID with their 20 most recent posts including title, content, and created date" \
  -u

The component code doesn't change. The types update automatically. Done.

Reliability Without Manual Review

When agents generate code from scratch, you need to review everything. With Corsair:

The agent's job:

Decide what data is needed
Write the natural language description
Use the generated query

Corsair's job:

Generate type-safe implementation
Handle ORM specifics
Integrate with your schema
Update when schema changes

Your job:

Review the natural language description (easy to skim)
Trust that Corsair handles the implementation correctly

Plugin Integration

Agents can create mutations that use plugins without writing integration code.

pnpm corsair mutation \
  -n "onboard new user" \
  -i "create user account, send welcome email via SendGrid, create onboarding tasks, and post to #new-users Slack channel"

What the agent gets:

Fully typed mutation
Safe plugin integration
No manual API client setup
No auth token management

What you get:

Vetted plugin implementations
Consistent error handling
Automatic updates when plugins change

The Goal

Corsair's CLI enables:

Agent-first development — agents create queries and mutations via CLI
Minimal context usage — delegate implementation to Corsair instead of generating inline
Type safety — all generated code is fully typed
Reduced technical debt — consistent, vetted implementations
Fast iteration — update queries with a single command
Plugin access — agents can use third-party services without writing integrations

You get the speed of coding agents with the reliability of hand-written code.

CLI Concepts

On this page