Guides / Agent workflow · Reviewed September 24, 2026 · Cloud CLI 0.1.33 / platform 2.7.241

Build with Codex and Claude Code

Give your agent a live development app, the current framework contract, and a clear way to prove its changes work. Both agents use the same Benmore skill and app instructions.

This guide uses Benmore's hosted platform. Your editor contains source; the deployed development URL runs the app. For your own server, follow the self-hosting guide and the framework edition's app instructions.

1. Install and connect

# macOS
brew install benmore-studio/benmore/benmore-cli

# Linux: use this instead of Homebrew
curl -fsSL https://benmore.ai/install-cli.sh | sh

benmore version --json
benmore bootstrap

Check for the cloud edition. The cloud CLI and runtime have independent version numbers. Bootstrap authenticates through the browser (benmore.ai requires the emailed sign-in code), creates the workspace, installs complete Codex and Claude skill bundles, merges Claude edit hooks, and attempts to pull accessible apps. Inspect the sync results before assuming every app is present.

To install only the skills into an existing setup:

benmore skill install --agent all
benmore skill path --agent codex
benmore docs harness
benmore docs build

Harness	Shared instructions	How edits reach the app
Codex	App `AGENTS.md`; skill at `~/.agents/skills/benmore-cli`. Invoke `$benmore-cli`.	Run `benmore push <file>` explicitly.
Claude Code	App `CLAUDE.md` imports `AGENTS.md`; skill at `~/.claude/skills/benmore-cli`.	Installed hooks handle matching Edit/Write tools. Shell edits and other unmatched tools require an explicit push.

Bootstrap also installs workspace skill copies. Start your agent in the app directory and start a fresh session if it does not see newly installed instructions. --agent codex and --agent claude target one harness; omitting --agent retains the legacy Claude default. Agent targets require CLI 0.1.30 or newer. Benmore does not install a Codex save hook or change your agent's approval settings.

For an external chat client, use the connection guide and https://benmore.ai/mcp. Read help(topic:"harness") and help(topic:"build") there. The chat stays in your external client; the Benmore dashboard manages apps.

2. Choose the app and environment

benmore whoami
benmore apps
benmore use dev
benmore sync-status --all

# For a new app after bootstrap:
cd ~/Benmore
benmore new crm
cd ./crm
benmore deploy
benmore open .

new crm creates ./crm and prints the resolved path. Use the actual directory and HTTPS URL returned by the CLI. Existing apps should be synced and inspected before you overwrite their source. --env dev or --env prod selects an environment for commands that accept it; use changes the saved selection.

Dev and prod have separate databases and secrets. A locally edited file is not necessarily the active deployed file, and the local workspace is not a copy of production data. State the intended app, environment, and observed identity in the task.

3. Read the live contract before coding

benmore api crm harness --env dev
benmore api crm schema --env dev
benmore api crm auth --env dev
benmore api crm flows --env dev
benmore api crm recovery --env dev

The topic is positional. In MCP, use api(at:"schema") and the corresponding topic for the selected app. These recipes describe the deployed implementation; installed help describes the local binary. Inspect real table columns, current access rules, existing flows, and actual response envelopes before writing an integration.

Use the CRUD API or bm SDK for normal user-facing mutations so validation, authorization, audit, hooks, and real-time effects all run. A hidden button is not access control. SQL flows need their own explicit authority and row-count checks; a zero-item loop is not proof an import succeeded.

Core YAML shape matters: cron jobs: is a list, OAuth provider metadata is top-level oauth:, and auxiliary loaders have their own limits. Read the feature recipe instead of extrapolating a nearby example.

4. Edit and deliver source

# From the app directory, after editing this file:
benmore push static/index.html
benmore check crm --env dev
benmore sync-status .

Push each changed source file and inspect each result. A multi-file upload is not a transaction across all files. Source-write success can acknowledge a queued reload; verify the app actually activated the change. A rejected core configuration reload keeps the active handler and workers, but does not undo committed migrations or external effects.

Keep credentials out of source and set them for the intended environment through the hosted environment controls. Do not deploy env.yaml, local databases, node_modules, or agent settings. Native HTML/TSX uses embedded compilation; an existing Vite or Next.js frontend must be built in its original project and copied as browser output. See the terminal guide.

5. Prove the result

Run the deployed app check and inspect server errors. It checks the selected deployed state, not your unsent local edits.
Exercise the changed route and inspect the persisted result. A successful HTTP response does not prove JavaScript executed or a database row changed.
Use a browser to perform the real journey, including form submission, loading/error states, and narrow screens. Check console errors and failed requests.
Test the relevant authorization boundary with a second identity: a user outside the owner/group should not gain access.
Run configured app verification, then require clean source synchronization for the app. Report unrelated workspace drift separately.

benmore verify .
benmore verify . --release
benmore sync-status .
benmore sync-status --all

verify reads the app's verification contract and journeys and writes evidence under .benmore/verify/<run-id>/. Define the relevant tests using api(at:"verification"); a missing named journey fails rather than being skipped. For MCP browser checks, inspect the current action schema: fill needs selector and text, and select needs selector and value.

6. Release and recover

benmore status crm
benmore diff crm
benmore doctor crm
benmore promote crm --dry-run
benmore ship . --promote

ship --promote requires an interactive terminal, performs release verification, rechecks source identity, and enters the confirmed promotion flow. Do not fake a terminal to bypass it. Review the selected production app and schema changes before completing promotion.

Operation	Effect and boundary
Promote	Moves source dev → prod. It preserves production data/secrets/uploads and applies needed migrations with backup safeguards. Destructive schema changes need explicit force approval.
Publish	Changes the testing/publication posture. It is separate from moving code between environments.
Refresh dev	Replaces the selected dev files/data from prod. Data refresh includes the matching encryption key; dev then contains real production data. Review the requested mode.
Source revert	Restores source history. It cannot restore deleted rows, undo committed migrations, or retract external messages/payments.
Database restore	Replaces data from a chosen snapshot. The platform validates it, stops/drains writers, preserves the previous database bundle, and verifies a fresh runtime. Writes after the snapshot are lost.

Read api(at:"environments") and api(at:"recovery") before recovery work. Since 2.7.226, covered lifecycle operations serialize per app, restore/refresh ordering protects database and key pairing, and restart success requires runtime activation evidence. A failed operation can still have committed effects; inspect its stage and recovery details before retrying.

Automation and troubleshooting

For headless hosted access, use BENMORE_TOKEN as an ephemeral process credential or benmore login --token, with a token from an earlier browser sign-in. benmore.ai refuses password-only CLI sign-in and CLI signup because it requires the emailed code. Do not print secrets. Explicit login --token validates and saves the token; the environment variable alone does not replace saved credentials.

Signal	Next action
`sync-status` 0 / 1 / 2 / 3	Clean / drift / conflict / setup or remote failure. Reconcile the actual condition before overwriting files.
General CLI 2 / 4 / 5 / 1	Usage / auth or authorization / missing or inaccessible app / transport or server failure. Sync has its own contract above.
Old page after a push	Inspect environment selection, reload logs, health receipts, and the source manifest. Do not equate queued delivery with activation. `/static/` script URLs carry a `?v=` hash of every file under `static/`; the framework replaces any `?v=` you write, and another query string turns that off for the reference.
Slow restart or migration	Inspect process/log/health progress. Avoid repeatedly interrupting initialization.
Skill missing	Check the installed edition/version, `skill path --agent codex`, app instructions, and a fresh agent session.

Usage telemetry is enabled by default, with a disclosure before the first upload. Normal CLI startup and Claude session-end hooks may sync attributed numeric counters; benmore usage sync forces a sync. Disable it with benmore telemetry off or BENMORE_TELEMETRY=0; benmore usage --local --json reads local numeric counters. See api(at:"agent-usage") for the current payload and privacy contract. Source, secrets, customer content, billing, and outbound messages retain their own authorization requirements.