Install the CLI

The CLI is the automation surface for platform-owned operations. It also builds and validates the repository-owned business program locally.

Install#

Farther Shore requires Node.js 22 or newer.

npm install -g @farthershore/[email protected]
farthershore --version

Sign in#

farthershore login

The CLI opens the complete authorization request in your browser without printing a code. A human approves the request. This is a user-bound login: the session acts as your current Farther Shore user across all current and future organization and business memberships. Normal login offers no permission or scope choices.

On a remote machine, print the manual verification URL and short-lived code without trying to open a local browser:

farthershore login --headless

The code expires, so complete the browser step while the command is polling. The CLI validates the credential before saving it and never needs a secret in a command-line argument.

Organizations#

One signed-in user can belong to multiple organizations. See them and select a default context without signing in again:

farthershore auth organization list
farthershore auth organization use acme
farthershore auth whoami

Override the selected organization for one command with the global --organization <id-or-slug> option.

Authorization uses live role evaluation rather than a copied permission list. Membership and role changes take effect on the next authenticated request.

Restricted automation override#

When a human intentionally issues an organization-scoped automation credential, pipe it over stdin instead of placing it in process arguments:

printf '%s' "$FARTHERSHORE_MAKER_TOKEN" | farthershore login --token-stdin

For a single invocation, FARTHERSHORE_TOKEN is an ephemeral environment override and is not persisted automatically. Use this path only when automation must be narrower than the signed-in user's live authority; the regular login flow remains the default.

Agent output#

Use JSON for scripts and agents:

farthershore business list --format json --no-input

Successful commands return an operation-keyed data envelope. Failures include a stable error code and remediation hint. Use farthershore <group> --help or farthershore operations list --format json instead of guessing command names.

Sign out#

farthershore logout

farthershore logout revokes the current CLI session and deletes the local credential file.