PromptFloe CLI

@promptfloe/cli is published on the public npm registry. Requires Node.js 20+. The binary is promptfloe (pure ESM).

npm i -g @promptfloe/cli
# or: pnpm add -g @promptfloe/cli

promptfloe --version

git clone <repo> promptfloe-cli && cd promptfloe-cli
pnpm install
pnpm build

# expose the built binary globally as `promptfloe`
cd packages/cli && npm link      # or: pnpm link --global

promptfloe --version
promptfloe --help

Setup is one command - promptfloe login. Your PromptFloe account is the only credential you manage; cloud commands run on our infrastructure and code intelligence needs nothing at all.

promptfloe login
# → Open https://promptfloe.com/device and enter code: WXYZ-1234
# → Waiting for approval…

export ANTHROPIC_API_KEY=sk-ant-...     # claude models (default)
# export OPENAI_API_KEY=sk-...          # for --model gpt-*
# export GEMINI_API_KEY=...             # for --model gemini-*

agent works a change in the current repo. It runs in one of three autonomy modes - the safest, plan (read-only), is the default. Every file path it touches is resolved and asserted inside your repo root before any read or write.

# Plan a change (read-only, safe)
promptfloe agent "add rate limiting to the /login route"

# Confirm each edit
promptfloe agent "extract the auth guard into a hook" --write

# Unattended, but only the Edit + Write tools are cleared
promptfloe agent "rename getUser to fetchUser everywhere" --auto --allow-tools Edit,Write

# Edit, then run the repo's verify and loop until green (max 5 attempts)
promptfloe agent "fix the failing billing tests" --auto --verify --max-iterations 5

# Pick a model / add a cross-provider fallback for pre-stream failures
promptfloe agent "refactor the parser" --model sonnet --fallback-model gpt-4o

# Headless (print mode) - for scripts / CI
promptfloe agent "summarize what changed in src/" -p --output-format json

promptfloe chat starts a multi-turn REPL. Prose lines are agent turns (read-only by default); lines starting with / are slash commands. A statusline shows model · turns · tokens above each prompt (hide it with PROMPTFLOE_STATUSLINE=0).

Generate and manage full apps on PromptFloe's infrastructure from the terminal - the same control plane the web studio uses:

promptfloe build "a CRM pricing page, three tiers, dark violet theme"
promptfloe apps                       # list your generated cloud apps
promptfloe pull <appId> --dir ./crm   # download the files locally
promptfloe iterate <appId> "add an annual toggle" --tier pro --pull
promptfloe logs <appId>               # latest-deployment logs
promptfloe ship --target vercel --dir ./crm --name my-crm
promptfloe down <appId>               # take a deployment offline

schedule registers a cloud routine that runs a prompt on a cron cadence on our infrastructure - it survives your machine being off, with run history and server-side scheduling. It's built on the same durable job engine (BullMQ + Postgres) as the studio's Loops.

promptfloe schedule create "@daily" "generate a fresh sales dashboard from yesterday's data"
promptfloe schedule create "0 9 * * 1" "summarize open issues" --llm --tier pro
promptfloe schedule list
promptfloe schedule rm <id>

# --local instead PRINTS an OS-cron line for you to install (never touches the network)
promptfloe schedule create "@daily" "nightly cleanup" --local

workflow runs a JavaScript script that orchestrates many agent turns deterministically. The structure - what fans out, what verifies, what loops - is ordinary JS, so runs are reproducible and each step is independently checkable. Each ctx.agent(prompt) is one headless turn.

promptfloe workflow list
promptfloe workflow run review --args '{"target":"src/"}'
promptfloe workflow run ./scripts/migrate.mjs

Author one at .promptfloe/workflows/<name>.mjs exporting run(ctx):

export async function run(ctx) {
  const dims = ["correctness bugs", "security issues", "performance"];
  // Each dimension reviews, then its findings verify - no barrier between them.
  const findings = await ctx.pipeline(
    dims,
    (dim) => ctx.agent(`Review ${ctx.args?.target ?? "src/"} for ${dim}. ` +
      `Return JSON {"findings":[{"title":"..."}]}`, { schema: {} }),
    async (review) => ctx.parallel(
      (review?.findings ?? []).map((f) => async () => {
        const v = await ctx.agent(`Is "${f.title}" a real issue? JSON {"real":true|false}`, { schema: {} });
        return v?.real ? f : null;
      }),
    ),
  );
  return { confirmed: findings.flat().filter(Boolean) };
}

The runtime gives your script agent() (one turn → text, or JSON with schema), parallel(thunks) (concurrent barrier), pipeline(items, ...stages) (each item through every stage, no barrier), log(), and args. Fan-out is bounded by a concurrency cap.

The CLI keeps a fast, tree-sitter structural index of your repo so the agent - and you - can resolve symbols instantly. It's cached to disk and rebuilt incrementally (only changed files reparse).

promptfloe index               # build/refresh .promptfloe/index/index.json
promptfloe index --rebuild     # force a full rebuild
promptfloe symbols "handleAuth"   # fuzzy, ranked symbol search
promptfloe outline src/app.ts     # a file's ordered symbol tree

The CLI reads configuration from environment variables. The most common:

Global flags work on any command: --json (machine-readable output), --quiet, --no-color, --version. On-disk state lives under ~/.promptfloe/ (credentials, config) and .promptfloe/ in each repo (sessions, structural index) - both gitignored.

The agent is built to be trusted with your repo. The guardrails below are enforced by the native engine (the default):

• Path jail. Every file the agent reads or writes is resolved (symlinks included) and asserted inside your repo root before the filesystem is touched - no ../ escapes, no absolute-path smuggling.
• Permission gate. One policy decides every tool call: reads are always allowed; writes and shell are denied in plan, prompted in confirm, and in auto allowed only if on your --allow-tools list.
• Secret protection. Sensitive paths (.env, .ssh, .aws, *.pem, .git-credentials…) are refused for read and write in every mode. Outbound model traffic is scrubbed for API-key / token / JWT / connection-string shapes before it leaves your machine.
• Shell denylist. The Bash tool refuses catastrophic commands (rm -rf / / ~ / $HOME, force-push, fork bombs, curl … | sh) and kills the whole process tree on timeout.
• Undo & checkpoints. Write-runs are checkpointed; promptfloe checkpoints lists them and promptfloe undo reverts a run's changes.

The CLI is a pnpm + Turborepo monorepo. To run it from a clone:

git clone <repo> promptfloe-cli && cd promptfloe-cli
pnpm install
pnpm build            # topological: lexicon, kavach, … then cli
pnpm typecheck
pnpm test             # vitest unit tests (co-located *.test.ts)

# run the built binary
node packages/cli/dist/index.js --help
node packages/cli/dist/index.js agent "explain src/index.ts" -p

End-to-end tests run against the built binary in an isolated home directory (so they never touch your real ~/.promptfloe):

pnpm build && pnpm --filter @promptfloe/cli test:e2e