Fargo AI CLI

fargo is the Agent-neutral command-line client for Fargo AI. Codex, Claude Code, Cursor, WorkBuddy, and future shell-capable Agents share the same Fargo identity, hosted MCP contracts, and deterministic LEGO project operations.

Requires Node.js 20.19 or newer.

Install or upgrade

npm install -g @fargowealth/fargo-ai-cli@latest
fargo version

Install the Fargo MCP connection with one command for the selected Agent:

npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=codex --open-browser=always --output=jsonl
npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=claude-code --open-browser=always --output=jsonl
npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=cursor --open-browser=always --output=jsonl
npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=workbuddy --open-browser=always --output=jsonl
fargo auth status

Run only the line for the Agent being configured. The command completes OAuth Authorization Code + PKCE over an ephemeral IPv4 loopback callback, writes the Agent's user-level local stdio MCP entry, and reports installed=true. It is normally run once; the rotating credential is then refreshed automatically and reused by both MCP and local CLI operations.

MCP boundary

• Hosted MCP owns Fargo resources, permission checks, status, publication, rollback, Cloudflare writes, and D1 execution.
• CLI owns local walking, exclusions, ZIP creation, hashing, binary transfer, deploy composition, and migration-file ordering.
• CLI has no generic R2 or Cloudflare administration commands.
• fargo mcp serve is the local stdio bridge for WorkBuddy, Claude Code, Codex, and Cursor.
• fargo mcp tools and fargo mcp call support scripts and one-shot diagnostics without starting an MCP host.

fargo mcp tools
fargo mcp call lego_app_read --args '{"action":"get","appId":"app_xxx"}'
fargo mcp call lego_app_read --args-file ./arguments.json

Website Connectors

fargo website is the authoring and control surface for cloud-hosted Website Connectors. Connector definitions and immutable releases are stored by Fargo Website Bridge; per-user Cookie/localStorage remains encrypted in BrowserGateway and is never written to the CLI credential store or emitted as a JSON file. The CLI keeps a dedicated local Chrome Profile so the user can log in locally and synchronize later; that Profile is isolated from the user's normal Chrome data.

fargo website validate --file connector.json
fargo website runtime
fargo website release --file connector.json --expected-revision 0 --confirm
fargo website list
fargo website operations --connector earningshub
fargo website connect --connector earningshub
fargo website sync --connector earningshub
fargo website sync --connector earningshub --no-prompt --settle-ms 5000
fargo website connection-status --connector earningshub
fargo website call --connector earningshub --operation get_symbol --args '{"symbol":"AMZN"}'
fargo website call --mode local --file connector.json --operation get_symbol --args '{"symbol":"AMZN"}'
fargo website binding

connect opens the Connector login URL in a Fargo-owned local Chrome Profile. After login, the CLI captures only the Connector-declared Cookie and localStorage selectors. MCP negotiates a five-minute, single-use upload capability using SHA-256 digests; the Profile body then goes directly to https://website-bridge.fargowealth.app and never crosses the central MCP. sync reopens the same local Profile and uses optimistic Profile-version protection before replacing the encrypted cloud state. --no-prompt is for a Profile that is already authenticated.

Connectors can declare refresh-only storage selectors separately from request headers. For AWS Cognito, Browser Gateway exchanges the encrypted Refresh Token for new ID/access tokens before expiry, saves any rotated Refresh Token inside the same connection-scoped Durable Object, and only then continues the website operation. Refresh Tokens never enter MCP arguments, command output, or normal website requests. sync is required again only after Cognito rejects or revokes the Refresh Token.

Connector operations remain brokered through App MCP website-bridge, so the same operations are available to Codex, WorkBuddy, other Agents, and Teammates. V1 releases are owner-private. A Teammate binding delegates the invoking user's identity and contains neither a connectionId nor website credentials. The old authorize / authorize-complete Cloud Live View commands remain an optional fallback, not the primary connection path.

For V3 development, --mode local opens the isolated local Profile and executes the definition with the same @fargowealth/website-connector-runtime package used by Browser Gateway. Local mode never uploads its captured Profile. Remote mode remains the default and authoritative path for production Agents and Teammates. fargo website runtime prints the local Runtime version and supported capabilities so Connector requirements can be checked before execution.

LEGO source snapshots

fargo lego snapshot upload --app app_xxx --source . --version 1.4.0 --name "Pre-upgrade backup" --dry-run
fargo lego snapshot upload --app app_xxx --source . --version 1.4.0 --name "Pre-upgrade backup" --notes "Before migration"
fargo lego snapshot list --app app_xxx
fargo lego snapshot download --app app_xxx --snapshot snap_xxx

The CLI applies secure defaults plus .legoignore, skips symbolic links, creates a deterministic ZIP, calculates SHA-256 digests, and uploads raw bytes over authenticated HTTP. The ZIP includes .fargo-snapshot/manifest.json; its default archive limit is 50 MB. An upload creates a downloadable source-backup history event without deploying or publishing the App.

LEGO local deploy

Run the project build explicitly, then give Fargo CLI the completed output:

npm run build
fargo lego deploy \
  --app app_xxx \
  --source . \
  --source-exclude node_modules/ \
  --deploy-dir dist \
  --target pages \
  --entrypoint index.html \
  --version 1.4.0 \
  --name "Navigation refresh" \
  --notes-file CHANGELOG.md

For Workers use --target worker; the default entrypoint becomes index.js. The CLI does not install dependencies, infer a framework, or run the build. Version number, version name, and upgrade notes are required. Source upload is the default; --skip-source is the explicit exception for a deployment that must not retain a source archive.

Full-stack Workers can include Cloudflare Worker Static Assets without giving the local CLI Cloudflare credentials:

fargo lego deploy \
  --app app_xxx \
  --source . \
  --deploy-dir .build/worker \
  --target worker \
  --entrypoint index.js \
  --assets-dir dist \
  --assets-binding ASSETS \
  --assets-not-found-handling single-page-application \
  --assets-run-worker-first \
  --login-required yes \
  --version 1.4.0 \
  --name "Full-stack release" \
  --notes-file CHANGELOG.md

Use repeated --assets-run-worker-first-route <glob> options instead of the boolean flag when only selected routes should invoke the Worker first. The hosted LEGO publisher uploads the assets and attaches the binding; Cloudflare credentials remain server-side.

.fargo-assets/ is an internal archive directory reserved for Fargo CLI. Do not create it, copy frontend files into it, or place browser output inside the Worker --deploy-dir. Always provide the original frontend build directory through --assets-dir; the CLI packages it under .fargo-assets/ and emits the required schema v2 metadata. Worker deploys fail early when they contain a manual .fargo-assets/, a root index.html, overlapping deploy/assets directories, or asset options without --assets-dir.

Run fargo lego deploy --help for the complete option list and a full-stack Worker example. A dry run reports the manifest schema version and separate Worker-module and Static Asset file counts.

Use --login-required no to prepare a public deployment with no access scope. Use --login-required yes to require company-account sign-in; when the current App is public, the hosted deployment defaults its scope to Collaborators and Owner only. Company-wide and specific-member scopes remain available through the hosted MCP deployment contract.

Pass --source-exclude <gitignore-pattern> once or multiple times when a release command must make additional source exclusions explicit. Secure defaults already exclude node_modules/, build output, credentials, and common generated directories; explicit rules are included in dry-run output.

The command creates and uploads two immutable archives:

1. a filtered source snapshot for recovery and provenance;
2. a deterministic deployment ZIP from --deploy-dir using .legodeployignore.

It then sends only sourceSnapshotId and deployArtifactId through the hosted MCP deployment contract. The result is ready, never automatically published. Use --dry-run to validate both local packages without authentication or network writes.

Deployment artifacts preserve binary bytes and include .fargo-deploy/manifest.json. Default limits are 1,000 files, 25 MB total, 20 MB per file, and a 25 MB ZIP.

LEGO D1 migrations

# Schema-only migrations also require the authoritative local prefix assertion
fargo lego d1 migrate plan --app app_xxx --dir migrations --table-prefix app_code_
fargo lego d1 migrate apply --app app_xxx --dir migrations --table-prefix app_code_

# Controlled data migrations: review the reported impact first
fargo lego d1 migrate plan \
  --app app_xxx \
  --dir migrations \
  --table-prefix app_code_

# Run only after a separate explicit approval of that plan
fargo lego d1 migrate apply \
  --app app_xxx \
  --dir migrations \
  --table-prefix app_code_ \
  --allow-data-migrations

Migration files are top-level, lexically ordered *.sql files. The filename without .sql is the version. plan compares local SHA-256 values with the production registry; apply stops on content drift and submits only pending files. The plan reports statement types, data-mutation types, target tables, and whether separate data-migration approval is required.

Schema DDL remains the default. Every migration command requires --table-prefix; the token parser applies it to table names, index names, index targets, and foreign-key references before MCP is contacted. The opt-in data mode accepts INSERT ... VALUES with optional ON CONFLICT, plus UPDATE and DELETE only when they contain a WHERE clause. Data targets must use the server-derived App table prefix; system tables, cross-table queries, PRAGMA, ATTACH, and DROP remain blocked. The service independently derives the authoritative prefix and rejects a mismatched client assertion. Each migration file executes as one transactional D1 batch, server-side and independently from deploy.

Compatibility and repair

npx -y @fargowealth/fargo-ai-cli@latest workbuddy install --open-browser=always --output=jsonl

The legacy WorkBuddy command is an alias for the unified Agent installer. Installers preserve unrelated MCP servers. Rerun the unified command only to upgrade or repair a Fargo entry. Device Authorization Grant remains an explicit fallback:

fargo auth device --open-browser=always --output=jsonl

Credential storage

• macOS and Linux: ~/.fargo/credentials.json
• Windows: %APPDATA%\Fargo AI\credentials.json

macOS/Linux use a 0700 directory and 0600 file. Windows inherits the current user's NTFS ACL. Writes use an fsync-backed temporary file and atomic replacement, symbolic-link reads are rejected, and refresh-token rotation is serialized across CLI processes.

Never copy, upload, commit, or print the credential file. Use fargo auth logout when a device is no longer trusted.