eve-app-cli

Eve App CLI

Build domain-specific CLIs for Eve-compatible apps so agents interact via commands instead of raw REST calls.

Why

Agents waste 3-5 LLM calls per REST interaction on URL construction, JSON quoting, auth headers, and error parsing. A CLI reduces this to 1 call:

# Before (3-5 calls, error-prone)
curl -X POST "$EVE_APP_API_URL_API/projects/$PID/changesets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EVE_JOB_TOKEN" \
  -d @/tmp/changeset.json

# After (1 call, self-documenting)
eden changeset create --project $PID --file /tmp/changeset.json

Quick Start

1. Create the CLI Package

your-app/
  cli/
    src/
      index.ts          # Entry point
      client.ts         # API client (reads env vars)
      commands/
        projects.ts     # Domain commands
    bin/
      your-app          # Built artifact (single-file bundle)
    package.json
    tsconfig.json

2. Implement the API Client

// cli/src/client.ts — Copy this, change SERVICE name
const SERVICE = 'API';

export function getApiUrl(): string {
  const url = process.env[`EVE_APP_API_URL_${SERVICE}`];
  if (!url) {
    console.error(`Error: EVE_APP_API_URL_${SERVICE} not set.`);
    console.error('Are you running inside an Eve job with with_apis: [api]?');
    process.exit(1);
  }
  return url;
}

export async function api<T = unknown>(
  method: string,
  path: string,
  body?: unknown,
): Promise<T> {
  const url = getApiUrl();
  const token = process.env.EVE_JOB_TOKEN;
  const res = await fetch(`${url}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({} as Record<string, string>));
    console.error(`${method} ${path} → ${res.status}: ${err.message || res.statusText}`);
    process.exit(1);
  }
  return res.json() as Promise<T>;
}

3. Define Commands

// cli/src/index.ts
import { Command } from 'commander';
import { api } from './client.js';
import { readFile } from 'node:fs/promises';

const program = new Command();
program.name('myapp').description('My App CLI').version('1.0.0');

program.command('items')
  .command('list')
  .option('--json', 'JSON output')
  .action(async (opts) => {
    const items = await api('GET', '/items');
    if (opts.json) return console.log(JSON.stringify(items, null, 2));
    for (const i of items) console.log(`${i.id}  ${i.name}`);
  });

program.command('items')
  .command('create')
  .requiredOption('--file <path>', 'JSON file')
  .action(async (opts) => {
    const body = JSON.parse(await readFile(opts.file, 'utf8'));
    const result = await api('POST', '/items', body);
    console.log(`Created: ${result.id}`);
  });

program.parse();

4. Bundle for Zero-Dependency Distribution

Create a build script (cli/build.mjs):

import { build } from 'esbuild';
import { readFile, writeFile, chmod } from 'node:fs/promises';

await build({
  entryPoints: ['cli/src/index.ts'],
  bundle: true,
  platform: 'node',
  target: 'node20',
  format: 'cjs',          // CJS — commander uses require() internally
  outfile: 'cli/bin/myapp',
});

// Prepend shebang (esbuild banner escapes the !)
const code = await readFile('cli/bin/myapp', 'utf8');
await writeFile('cli/bin/myapp', '#!/usr/bin/env node\n' + code);
await chmod('cli/bin/myapp', 0o755);

Add to package.json:

{
  "scripts": {
    "build": "node build.mjs"
  }
}

Important: Do NOT set "type": "module" in package.json — it causes require() errors at runtime. Use .mjs extension for the build script instead.

5. Declare in Manifest

# .eve/manifest.yaml
services:
  api:
    build:
      context: ./apps/api
    ports: [3000]
    x-eve:
      api_spec:
        type: openapi
      cli:
        name: myapp           # Binary name on $PATH
        bin: cli/bin/myapp     # Path relative to repo root

The platform automatically makes the CLI available to agents that have with_apis: [api].

Design Rules

Command Structure

Map CLI commands to your domain, not HTTP endpoints:

# Good — domain vocabulary
eden map show
eden changeset create --file data.json
eden changeset accept CS-45

# Bad — HTTP vocabulary
eden get /projects/123/map
eden post /changesets --body data.json

Output Contract

• Default: human-readable (tables, summaries)
• --json: machine-readable JSON on stdout
• Errors: stderr, exit code 1, actionable message

eden projects list              # Table: ID  NAME  CREATED
eden projects list --json       # [{"id":"...","name":"..."}]
eden changeset accept BAD-ID    # stderr: "Changeset BAD-ID not found"

Auto-Detection Pattern

When only one resource exists, auto-detect instead of requiring flags:

async function autoDetectProject(): Promise<string> {
  const projects = await api('GET', '/projects');
  if (projects.length === 1) return projects[0].id;
  if (projects.length === 0) {
    console.error('No projects found.');
    process.exit(1);
  }
  console.error('Multiple projects. Use --project <id>:');
  for (const p of projects) console.error(`  ${p.id}  ${p.name}`);
  process.exit(1);
}

Progressive Help

Every command and subcommand has --help:

$ eden --help
Eden story map CLI

Commands:
  projects    Manage projects
  map         View story map
  changeset   Create and review changesets
  persona     Manage personas
  question    Manage questions
  search      Search the map
  export      Export project data

$ eden changeset --help
Commands:
  create   Create a changeset from JSON file
  accept   Accept a pending changeset
  reject   Reject a pending changeset
  list     List changesets for a project

Environment Variables

The CLI reads these from the environment (injected automatically by Eve):

Variable	Purpose	Set By
EVE_APP_API_URL_{SERVICE}	Base URL of the app API	Platform (--with-apis)
EVE_JOB_TOKEN	Bearer auth token	Platform (per job)
EVE_PROJECT_ID	Eve platform project ID	Platform
EVE_ORG_ID	Eve platform org ID	Platform

The CLI never requires manual configuration.

Testing Locally

Set env vars and run directly:

export EVE_APP_API_URL_API=http://localhost:3000
export EVE_JOB_TOKEN=$(eve auth token)

# Test individual commands
./cli/bin/myapp projects list
./cli/bin/myapp items create --file test-data.json

Bundling Details

Use esbuild to produce a single file with zero runtime dependencies:

• --bundle inlines all imports (including commander)
• --platform=node targets Node.js built-ins
• --target=node20 matches Eve runner environment
• --format=cjs uses CommonJS (commander uses require() internally)
• Shebang prepended separately (esbuild --banner escapes ! in #!/usr/bin/env)
• Result: 50-200KB single file, no node_modules needed at runtime

Commit cli/bin/myapp to the repo so it's available immediately after clone.

Image-Based Distribution (Compiled CLIs)

For Go, Rust, or other compiled CLIs:

services:
  api:
    x-eve:
      cli:
        name: myapp
        image: ghcr.io/org/myapp-cli:latest

Build a Docker image with the CLI binary at /cli/bin/myapp:

FROM rust:1.77 AS build
COPY . .
RUN cargo build --release

FROM busybox:stable
COPY --from=build /app/target/release/myapp /cli/bin/myapp

The platform injects it via init container (same pattern as toolchains, ~2-5s latency).

See Also

• references/app-cli.md in eve-read-eve-docs for the full technical reference
• references/manifest.md for manifest schema details
• references/eve-sdk.md for the Eve Auth SDK (server-side token verification)