# openpond

OpenPond CLI

The `openpond/app-server` entry point supports embedding the full Work runtime with application tool bindings, service controls and persistence callbacks. See the [embedding guide](https://github.com/openpond/openpond/blob/master/docs/public/app-server-embedding.md).

The generated [command reference](./docs/command-reference.md) is the authoritative command and option inventory.

Launch the complete local web app without installing it globally:

```bash
npx openpond@latest
```

The command starts a local OpenPond server, passes its authenticated URL directly to your system browser, and stays attached until you press `Ctrl+C`. Application state persists under `~/.openpond`; the directory where you invoke the command is not modified. npm maintains its own package cache separately.

Node.js 24.18 or newer in the Node 24 release line is required. Other installation and launch forms remain available:

```bash
npm install --global openpond
openpond

# Print the authenticated local URL instead of opening a browser.
openpond ui --no-open

# Launch the terminal UI explicitly.
openpond tui

# GitHub release installer for a compiled CLI.
curl -fsSL https://openpond.ai/install.sh | bash
```

Login (stores authentication in the encrypted home vault):

```bash
openpond login
# or (non-interactive)
openpond login --api-key opk_...
# or save under an account profile
openpond login --account production --api-key opk_prod_...
openpond login --account secondary --api-key opk_secondary_...
```

Desktop includes the five maintained OpenPond workflow skills automatically: `openpond-cli`, `openpond-taskset-authoring`, `openpond-agent-authoring`, `openpond-skill-authoring`, and `openpond-refiner-authoring`. Inspect their readiness, instructions, and bundled reference files in **Settings → Skills → OpenPond skills**. They belong to the app's runtime and do not require installation into your personal Codex skills directory.

Commands:

```bash
openpond --version
openpond --check-update
openpond profiles list
openpond profiles use production
openpond profiles save secondary --api-key opk_...
openpond account
openpond health
openpond extension add owner/repo
openpond extension list
openpond extension update --all
openpond actions check --cwd ./customer-project
openpond actions run analytics.get_summary --cwd ./customer-project --input '{"businessId":"relocation"}'
openpond --account production apps list
openpond tool list <handle>/<repo>
openpond tool run <handle>/<repo> <tool> --body '{"foo":"bar"}'
openpond deploy watch <handle>/<repo> --branch main
openpond template status <handle>/<repo>
openpond template branches <handle>/<repo>
openpond template update <handle>/<repo> --env production
openpond repo create --name my-repo --path .
openpond repo push --path . --branch main
openpond apps list [--handle <handle>] [--refresh] [--json]
openpond apps tools
openpond apps deploy <handle>/<repo> --env production --watch
openpond apps env get <handle>/<repo>
openpond apps env set <handle>/<repo> --env '{"OPENTOOL_PUBLIC_HL_SIGNAL_BOT_CONFIG":"..."}'
openpond apps performance [--app-id <id>]
openpond apps agent create --prompt "Build a daily digest agent"
openpond apps tools execute <appId> <deploymentId> <tool> --body '{"foo":"bar"}'
openpond opentool init --dir .
```

Global account selection:

- `--account <name>` (alias `--profile <name>`) selects which stored account/API key to use.
- `--base-url <url>` (alias `--baseurl`) selects the account entry matching that base URL when duplicate handles exist.
- `OPENPOND_ACCOUNT=<name>` sets the default selected account for a shell/session.
- If omitted, CLI uses the last active stored account.

Command reference:

- `openpond login`: prompt for an API key and save it in the encrypted home vault.
- `openpond login --api-key <key>`: save the API key without prompting.
- `openpond profiles list`: list redacted local accounts from the shared home configuration.
- `openpond profiles use <name> [--base-url <url>]`: switch the active local profile.
- `openpond profiles save <name> --api-key <key> [--base-url <url>] [--environment <name>]`: save or update a local profile API key.
- `openpond account`: fetch current account/profile fields and active products for the selected API key.
- `openpond health`: check public API reachability and selected API-key auth health when a key is configured.
- `openpond extension <add|preview|list|inspect|update|remove>`: manage Agent Skills-compatible GitHub packs installed under `~/.openpond/extensions`. Repositories use standard `SKILL.md` packages and do not need an OpenPond-specific manifest.
- `openpond actions <check|build|run|dev>`: validate, bundle, invoke, or watch typed Project Actions under `openpond/actions` in a local Project. This path is local and does not require an API key.
- `openpond tool list <handle>/<repo>`: list tools for the latest deployment.
- `openpond tool run <handle>/<repo> <tool> [--body <json>] [--method <METHOD>]`: run a tool on the latest deployment.
- `openpond deploy watch <handle>/<repo> [--branch <branch>]`: stream deployment logs for the latest deployment.
- `openpond template status <handle>/<repo>`: check whether a template update is available.
- `openpond template branches <handle>/<repo>`: list available template branches.
- `openpond template update <handle>/<repo> [--env preview|production]`: deploy the latest template commit.
- `openpond repo create --name <name> [--path <dir>] [--empty|--opentool] [--deploy-on-push]`: create an OpenPond repo and attach the git remote.
- `openpond repo push [--path <dir>] [--branch <branch>]`: push the current git branch using a tokenized remote (non-interactive, restores origin after push).
- `openpond apps list [--handle <handle>] [--refresh] [--json]`: list apps for your account, optionally filtered by handle.
- `openpond apps tools`: list tools for your account (public API).
- `openpond apps deploy <handle>/<repo> [--env preview|production] [--watch]`: trigger a deployment for an app.
- `openpond apps env get <handle>/<repo>`: get OPENTOOL_PUBLIC_* env vars for an app.
- `openpond apps env set <handle>/<repo> --env <json>`: set OPENTOOL_PUBLIC_* env vars for an app.
- `openpond apps performance [--app-id <id>]`: fetch performance summary, optionally scoped to an app.
- `openpond apps agent create --prompt <text> [--template-id <id>]`: create an agent from a prompt (streams deploy logs by default).
- `openpond apps tools execute <appId> <deploymentId> <tool> [--body <json>] [--method <METHOD>] [--headers <json>]`: execute a tool for a specific deployment.
- `openpond opentool <init|validate|build> [args]`: run OpenTool CLI commands via `npx opentool`.

Agent source operations:

- `openpond agent source checks <agentId> --team-id <id> [--check-kind <kind>]`: request validation or eval checks for an Agent source version.
- `openpond agent source publish <agentId> --team-id <id> [--expected-manifest-hash <hash>]`: publish a validated Agent source version.

## TypeScript package

Programmatic API that mirrors the CLI command surface:

```ts
import {
  createClient,
  listConfiguredProfiles,
  saveProfileApiKey,
  setActiveProfile,
} from "openpond";

const client = createClient({ apiKey: process.env.OPENPOND_API_KEY! });

const { tools } = await client.tool.list("handle/repo");
const result = await client.tool.run("handle/repo", "myTool", {
  body: { foo: "bar" },
});

const apps = await client.apps.list();
const account = await client.account.get();
const health = await client.account.health();
const accountTools = await client.apps.tools();
const performance = await client.apps.performance({ appId: "app_123" });
const repo = await client.repo.create({ name: "my-repo", repoInit: "empty" });

const profiles = await listConfiguredProfiles();
await setActiveProfile("0xglu", { baseUrl: "https://openpond.ai" });
await saveProfileApiKey({
  handle: "secondary",
  apiKey: "opk_...",
  baseUrl: "https://openpond.ai",
});

await client.apps.agentCreate(
  { prompt: "Build a daily digest agent" },
  {
    onItems: (items) => {
      for (const item of items) {
        console.log(item);
      }
    },
  }
);
```

You can override hosts with `apiUrl` and `toolUrl` in `createClient`, or
via `OPENPOND_API_URL` and `OPENPOND_TOOL_URL`.

Examples live in `examples`.


## Run

```bash
pnpm install
pnpm dev
```

Cache:

- `~/.openpond/cache.json` caches app/tool lists for 1 hour and refreshes automatically on next use.

### Experiment spending

`openpond experiments defaults --team <team-id>` reads the hosted global
spending defaults. New experiments use that default when `maximumCostUsd` is
omitted from the input file; include it to override a single run. The resolved
ceiling is retained with the experiment. Model calls, grading and compute count
against it, including reservations whose final charge is not yet known.

For multiple models, register one shared ceiling **before admitting any runs**:

```json
{
  "id": "comparison-unique-id",
  "maximumSpendUsd": 10,
  "operationIds": ["fresh-operation-a", "fresh-operation-b"]
}
```

Run `openpond experiments create-comparison --team <team-id> --input-file <path>`
with that file, then use those exact operation IDs in the normal
`prepare-harness` and `run` commands. Registration does not start models. Each
child keeps its per-experiment cap and also consumes the comparison's shared
cap. Read settled, reserved and remaining amounts with
`openpond experiments comparison-budget <id> --team <team-id>`.
Membership and the shared ceiling are immutable; an uncertain response is
retried with the same comparison ID and input, never a fresh set of runs.