CLI reference
Authenticate, discover capabilities, and operate every agent-accessible Farther Shore workflow.
Authenticate, discover capabilities, and operate every agent-accessible Farther Shore workflow.
The CLI is both a local business-program tool and the complete automation
surface for platform-owned state. Treat the installed CLI and its operation
catalog as canonical; documentation explains behavior, while --help supplies
the exact versioned flags.
farthershore login
farthershore auth whoami --format json
farthershore auth organization list --format json
farthershore auth organization use <id-or-slug>
Device login opens the complete authorization request in your browser without
printing a code and waits for a human to approve it. --headless instead prints
the manual verification URL and user code without opening a browser. Normal
login is user-bound and has no permission or scope choices: the CLI acts as the
user, and Core reloads that user's live role on every request.
Normal login includes all current and future organization and business access.
Membership and role changes take effect on the next authenticated request.
--organization <id-or-slug> selects command context for one invocation. It
never narrows the session's authority.
For deliberately restricted automation, pipe a pre-issued organization-scoped MakerToken from its secret provider:
printf %s "$FARTHERSHORE_MAKER_TOKEN" | farthershore login --token-stdin
Or set FARTHERSHORE_TOKEN for a single process. Never place the secret in
argv. farthershore logout revokes a user CLI session and deletes the local
credential; a saved MakerToken is removed locally but remains governed by its
server-side token lifecycle.
farthershore operations list --format json
farthershore business --help
The operation catalog currently publishes each operation's class, side-effect
class, CLI command, MCP mapping, and either its exact permission/target kind or
an explicit handoff with null authority. Only not_implemented is a platform
gap; repo_authored, git_triggered, subscriber_portal, human_decision,
and runtime_surface are deliberate boundaries. For example,
funding.top_up.purchase is discoverable as a subscriber_portal handoff but
has no builder permission, CLI command, or MCP tool; use its documented public
Frontend SDK path in the prepaid wallet cookbook.
Database-backed list commands that advertise the options share Core's list query contract:
farthershore business list --filter status=ACTIVE --search billing --sort updatedAt:desc
farthershore organization role list <organization-id> --filter builtIn=false --sort name
farthershore organization members <organization-id> --filter roleKey=member --sort email
farthershore env list <business> --search preview --sort name
Filtering and sorting happen on the server before pagination. --filter is
repeatable and exact; --search is case-insensitive; --sort defaults to
ascending when its direction is omitted. Each command's help prints its closed
field allowlist. See Platform access and roles.
CREATE_ATTEMPT=$(node -e 'console.log(crypto.randomUUID())')
REPO_URL=$(farthershore business create quillby \
--idempotency-key "$CREATE_ATTEMPT")
git clone "$REPO_URL"
This is the only creation path. Human-mode stdout is the repository URL and
success is impossible before the managed repository exists. Structured output
contains the business, repoUrl, and recovery metadata. On an ambiguous
timeout, retry the exact same intent with the persisted key, then run
business show; the replayed create result is not a fresh read.
The repository starts without a business shape. Author the filename-agnostic
business/ program, then:
farthershore build --format json
farthershore validate --format json
git push
farthershore apply-timeline list quillby --format json
| Job | Command groups |
|---|---|
| Business lifecycle and accepted contract | business, apply-timeline, plan, env |
| Customer and subscription operations | consumer, proposal, persona, promo-code, resource-count |
| Runtime application wiring | backend, variables, webhook, frontend |
| Observe and diagnose | business status, usage, analytics, denial, dependents, audit-log, workflows |
| Organization and personal context | auth, organization, notifications |
| Platform automation | agents, bulletin, automation, knowledge, workflow-control |
| Local repository tools | link, unlink, create, import, build, validate, frontend dev, frontend preview |
The top-level tax-settings group operates a business's Stripe Tax settings.
Use farthershore --help for the full current group list.
There is no CLI writer for plans, prices, routes, meters, resources, limits,
policies, or surfaces. Read them with commands such as business contract,
business routes, and plan list; change them in business/ and push.
Platform-owned metadata and live state use commands:
farthershore business update quillby --display-name "Quillby" --format json
farthershore business update quillby --unlist-from-org-page --format json
farthershore consumer list quillby --format json
The frontend group intentionally has no deploy subcommand. Preview frontend builds follow the
mapped preview branch; production frontend builds follow an approved GitHub
Release. The CLI inspects and recovers the result:
farthershore frontend status quillby --format json
farthershore frontend rollback quillby --release-id <releaseId> --dry-run --format json
fs.backend() declares a logical backend in business/. CLI backend commands
operate an environment-local instance, origin, tunnel, and runtime tokens:
farthershore backend list quillby --format json
farthershore backend create quillby --name api --transport direct --origin-url https://api.example.com --format json --idempotency-key <persisted-backend-create-attempt-key>
farthershore backend bind quillby <backendId> --origin-url https://preview-api.example.com --format json
farthershore backend tokens create quillby --backend <backendId> --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>
farthershore usage summary quillby --format json
farthershore analytics timeseries quillby --format json
farthershore audit-log list <organizationId> --format json
farthershore notifications preferences quillby --format json
These reads do not modify contract state.
business rollback starts a new publish workflow from a captured prior
snapshot and requires a caller-persisted attempt key. frontend rollback moves
the hosted release pointer and supports --dry-run. Neither rewrites Git
history. workflow-control rollback-to-config is preview-only: it computes the
configured rollback target but does not execute recovery, so it takes no key.
farthershore business rollback quillby <workflowExecutionId> --format json --idempotency-key <persisted-business-rollback-attempt-key>
farthershore workflow-control rollback-to-config quillby <configId> --format json
Read Releases before executing a production rollback.
Use --format json for the stable agent envelope:
{
"schema_version": 1,
"ok": true,
"op": "business.status",
"data": {}
}
Failures set ok: false and include a stable error.code, message, and
optional hint. Branch on code and process exit status; never parse the English
message.
| Exit | Meaning |
|---|---|
0 | success |
1 | local, not-found, or generic API failure |
2 | invalid request |
3 | authentication or authorization failure |
4 | MANAGED_BY_CODE ownership boundary |
5 | retryable platform or in-flight failure |
retry.kind and retry.reconcile from
farthershore operations list --format json.same_key_replay, persist one key before the first live dispatch and
reuse it only for that exact intent.read_current, convergent_write,
intrinsic_replay, or no_automatic_retry.convergent_write, run retry.reconcile before any
repeat. Repeat only if the original desired state is still authoritative;
then read again so an older request cannot overwrite a newer change.--dry-run where available, and never include an idempotency key in a
preview.--yes as an explicit destructive confirmation boundary.See Retries and idempotency for conflicts, in-flight attempts, secret recovery windows, and exact semantic request scope.