Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (iterate) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

iterate

⚠️⚠️⚠️ Coming soon! npx iterate is a work-in-progress CLI for managing iterate.com agents ⚠️⚠️⚠️

CLI for Iterate.

Runs as a thin bootstrapper that:

Resolves an iterate/iterate checkout.
Clones/install deps when needed.
Loads apps/os/backend/trpc/root.ts from that checkout.
Exposes commands like iterate os ... and iterate whoami.

Requirements

Node >=22
git
pnpm or corepack

Quick start

Run without installing globally:

npx iterate --help

Initial setup (writes auth + launcher config):

npx iterate setup \
  --os-base-url https://dev-yourname-os.dev.iterate.com \
  --daemon-base-url http://localhost:3001 \
  --admin-password-env-var-name SERVICE_AUTH_TOKEN \
  --user-email dev-yourname@iterate.com \
  --scope global

Then run commands:

npx iterate whoami
npx iterate os project list

Commands

iterate setup - configure auth + launcher defaults
iterate doctor - print resolved config/runtime info
iterate install - force clone/install for resolved checkout
iterate whoami
iterate os ...
iterate daemon ...

setup --scope global writes auth + launcher values into global; setup --scope workspace writes them into workspaces[process.cwd()].

Config file

Config path:

${XDG_CONFIG_HOME:-~/.config}/iterate/config.json

Config shape:

{
  "global": {
    "repoPath": "~/.local/share/iterate/repo",
    "repoRef": "main",
    "repoUrl": "https://github.com/iterate/iterate.git",
    "autoInstall": true
  },
  "workspaces": {
    "/absolute/workspace/path": {
      "osBaseUrl": "https://dev-yourname-os.dev.iterate.com",
      "daemonBaseUrl": "http://localhost:3001",
      "adminPasswordEnvVarName": "SERVICE_AUTH_TOKEN",
      "userEmail": "dev-yourname@iterate.com"
    }
  }
}

Merge precedence is shallow:

global -> workspaces[process.cwd()]

Repo checkout resolution

repoPath resolution order:

ITERATE_REPO_DIR
workspaces[process.cwd()].repoPath
global.repoPath
nearest parent directory containing .git, pnpm-workspace.yaml, and apps/os/backend/trpc/root.ts
default managed checkout path ${XDG_DATA_HOME:-~/.local/share}/iterate/repo

repoPath shortcuts in setup:

local - nearest local iterate checkout
managed - default managed checkout path

Environment overrides:

ITERATE_REPO_DIR
ITERATE_REPO_REF
ITERATE_REPO_URL
ITERATE_AUTO_INSTALL (1/true or 0/false)

Local iterate dev

If you run inside an iterate/iterate clone, the CLI auto-detects it. In that mode, default autoInstall is false.

You can pin explicitly:

npx iterate setup \
  --os-base-url https://dev-yourname-os.dev.iterate.com \
  --daemon-base-url http://localhost:3001 \
  --admin-password-env-var-name SERVICE_AUTH_TOKEN \
  --user-email dev-yourname@iterate.com \
  --scope workspace

Publishing (maintainers)

From repo root:

pnpm --filter ./packages/iterate typecheck
pnpm eslint packages/iterate/bin/iterate.js
pnpm prettier --check packages/iterate
pnpm --filter ./packages/iterate publish --access public