> ## Documentation Index
> Fetch the complete documentation index at: https://executor-typed-api-proxy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Run Executor as a local background service and drive it from the command line.

The CLI runs a small HTTP runtime on your machine: a durable background service
that any MCP-compatible agent can connect to. Your integrations, credentials, and
policies stay local.

## Install

Requires Node.js 20 or newer.

<CodeGroup>
  ```bash npm theme={null}
  npm install -g executor
  ```

  ```bash pnpm theme={null}
  pnpm add -g executor
  ```

  ```bash bun theme={null}
  bun add -g executor
  ```

  ```bash yarn theme={null}
  yarn global add executor
  ```
</CodeGroup>

## Start the service

Install the durable background service, then open the web UI:

```bash theme={null}
executor install   # install/start the durable background service
executor web        # open the web UI at http://127.0.0.1:4788
```

`executor install` registers Executor so it keeps running across restarts. For a
throwaway foreground runtime instead, run `executor web --foreground`.

## Connect an agent

Add Executor to any MCP client (Claude Code, Cursor, OpenCode) with `npx add-mcp`.
It detects the client and writes its config for you. Connect over HTTP or through
the CLI:

<Tabs>
  <Tab title="HTTP">
    Executor serves a streamable-HTTP MCP endpoint at `http://127.0.0.1:4788/mcp`:

    ```bash theme={null}
    npx add-mcp http://127.0.0.1:4788/mcp --transport http --name executor
    ```

    The **Connect** card in the web UI shows this command with your exact URL
    (and port, if it differs) already filled in.
  </Tab>

  <Tab title="CLI (stdio)">
    With the `executor` CLI on your PATH, the client launches `executor mcp`
    directly (no URL needed):

    ```bash theme={null}
    npx add-mcp "executor mcp" --name executor
    ```
  </Tab>
</Tabs>

## Add an integration

From the web UI, click **Add Source** and paste an OpenAPI, GraphQL, or MCP URL.
Executor detects the type, indexes the tools, and handles auth. Or add one from the
CLI:

```bash theme={null}
executor call executor openapi addSource '{
  "spec": "https://petstore3.swagger.io/api/v3/openapi.json",
  "namespace": "petstore",
  "baseUrl": "https://petstore3.swagger.io/api/v3"
}'
```

Use `baseUrl` when the OpenAPI document has relative `servers` entries (e.g. `"/api/v3"`).

Confirm it's live:

```bash theme={null}
executor tools sources   # lists configured integrations + tool counts
```

## Call tools

```bash theme={null}
executor tools search "send email"      # find tools by intent
executor call github issues --help      # browse a namespace
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
```

`executor call`, `executor resume`, and `executor tools …` auto-start the local
daemon if it isn't already running. If an execution pauses for auth or approval,
resume it:

```bash theme={null}
executor resume --execution-id exec_123
```

## Generate a typed client

`executor generate` exports your tool catalog as an OpenAPI 3.1 document:
one REST operation per tool, with full input/output schemas. Feed it to
whatever client generator you already use (openapi-typescript,
openapi-generator, Kiota, ...) and every call is typed end to end while still
executing through Executor (auth, policies, and approvals included):

```bash theme={null}
executor generate                        # writes executor.openapi.json
npx openapi-typescript executor.openapi.json -o executor-api.ts
```

The same document is served live at `GET /api/tools/export/openapi` (bearer
auth), so generators that take a URL can point straight at the instance. The
operations it describes are real endpoints: `POST /api/tools/invoke/{tool
path}` runs the tool and returns `{ ok: true, data }` or `{ ok: false, error }`;
approval-gated calls return `error.code: "execution_paused"` with resume
coordinates.

Prefer a ready-made client instead of running a generator? `--format
typescript` writes a single self-contained TypeScript file with a
dependency-free runtime client:

```bash theme={null}
executor generate --format typescript    # writes executor.gen.ts
executor generate --format both          # both artifacts
executor generate --integration github   # only one integration
```

```ts theme={null}
import { createExecutorClient } from "./executor.gen";

const executor = createExecutorClient(); // EXECUTOR_API_KEY / EXECUTOR_AUTH_TOKEN
const created = await executor.github.org.main.issues.create({ title: "Hi" });
if (created.ok) console.log(created.data.number);
```

Calls that pause for approval throw `ExecutorPausedError` with the approval
URL. Re-run `executor generate` whenever your catalog changes.