@farthershore/cli

Create and manage FartherShore API products from the terminal.

Install

npm install -g @farthershore/cli

Or use directly with npx:

npx @farthershore/cli init my-api

The package also ships an MCP stdio server for agents:

FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp

Authentication

Create an API token at farthershore.com/settings/tokens, then:

# Interactive — prompts for token
farthershore set-key

# Non-interactive — pass token directly
farthershore set-key mk_xxx

# Agent-friendly alias
farthershore auth set-key mk_xxx

# Environment variable (CI / agents)
export FARTHERSHORE_TOKEN=mk_xxx

Tokens are stored in ~/.farthershore/credentials.json.

Environment scope

Most product commands can run against production or a named environment. Production is the default. production, prod, and main all mean the production scope.

farthershore env create preview --branch env/preview --format json
farthershore env use preview --format json
farthershore plan list --env preview --format json
farthershore --env preview meter list --format json
farthershore env run preview -- plan add pro --price-monthly 2900 --format json
farthershore env use production --format json

env use is stored per product in ~/.farthershore/config.json, so switching products does not accidentally carry the previous product's environment.

Commands

farthershore init <name>

Create a new API product with a GitHub repo. Returns a clone URL and instructions for an AI agent (or human) to configure it.

farthershore init my-weather-api

Options:

• --base-url <url> — Backend API base URL
• --description <text> — Product description
• --display-name <name> — Display name for the product portal

The created repo contains:

• product.yaml — template config (edit and push to go live)
• AGENTS.md — full configuration reference for AI agents
• docs/ — developer portal documentation
• .skills/ — task-specific instructions

farthershore product create <name>

Create a product through the API and select it as the active product for subsequent CLI commands. This is the fastest path for an agent that wants to configure a product without opening the UI.

farthershore product create weather-api \
  --base-url https://api.example.com \
  --strategy prepaid_credits \
  --format json

farthershore product status

Return the latest accepted internal product config metadata, including the accepted config hash and GitHub sync state.

farthershore product status --format json
farthershore product status --env preview --format json

farthershore product config

Print the accepted or draft product config from FartherShore. GitHub, the UI, MCP, and the CLI all write through the same validated internal config path. Accepted config is live; draft config is staged until farthershore apply publishes it.

farthershore product config --format json
farthershore product config --format yaml
farthershore product config --state draft --format json
farthershore product config --env preview --format json

farthershore product attempts

List rejected config proposals. Invalid proposals are recorded for diagnostics but do not replace the accepted internal config or mutate live product state.

farthershore product attempts --format json
farthershore product attempts --env preview --format json

farthershore meter

Create and manage usage meters in the shared draft product config.

farthershore meter add ai_tokens \
  --selector model \
  --measure input_tokens \
  --measure output_tokens \
  --rating provider_catalog \
  --catalog llm_models \
  --format json

farthershore meter list --format json
farthershore meter list --env preview --format json

farthershore feature

Create features and bind or unbind them from plans.

farthershore feature add chat_completions \
  --route POST:/v1/chat/completions \
  --format json

farthershore feature bind chat_completions --plan pro --format json
farthershore feature list --env preview --format json

farthershore plan

Create and update plans in the shared draft product config. Server-side validation remains authoritative for rules like one free plan, duplicate paid prices, and product-level billing strategy consistency before apply can publish.

farthershore plan add free \
  --free \
  --limit ai_tokens:month:100000:enforce \
  --feature chat_completions \
  --format json

farthershore plan add pro \
  --price-monthly 2900 \
  --credits-monthly-micros 500000000 \
  --meter ai_tokens \
  --feature chat_completions \
  --format json

farthershore plan list --env preview --format json

farthershore billing

Read or change the product-level billing strategy and subscriber change policy.

farthershore billing strategy get --format json
farthershore billing strategy get --env preview --format json

farthershore billing strategy set prepaid_credits \
  --transition preserve_current_period \
  --format json

farthershore billing policy set \
  --default preserve_current_period \
  --proration none \
  --format json

farthershore transition preview

Preview how billing-affecting config changes apply to existing subscribers before applying them.

farthershore transition preview --format json
farthershore transition preview --env preview --format json

farthershore validate [file]

Validate a local product.yaml file without making any API calls. Checks structure, required fields, and launch constraints for env-scoped plans and meters.

# Validate product.yaml in current directory
farthershore validate

# Validate a specific file
farthershore validate path/to/product.yaml

farthershore apply [product]

Publish the shared server draft as one product release. Core accepts the release only after schema validation, transition-safety validation, and a compiler dry-run pass. Mutation commands such as meter add, feature add, and plan set-price stage draft changes by default; they do not create live product or plan versions until apply.

# Publish the current shared draft
farthershore apply

# Or pass the product slug explicitly
farthershore apply my-weather-api

# Validate and compile the draft without publishing
farthershore apply --dry-run --format json
farthershore apply --env preview --dry-run --format json

# Submit a local product.yaml as a one-off proposal
farthershore apply --to product.yaml --dry-run --format json
farthershore apply --to product.yaml --format json

# Also save that local file as the shared draft before publishing
farthershore apply --to product.yaml --save-draft --format json

Draft commands help agents inspect and control the release boundary:

farthershore draft status --format json
farthershore draft diff --format json
farthershore draft validate --format json
farthershore draft reset --format json

MCP tools

Run the MCP server with a maker token:

FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp

The MCP server exposes the same product-building workflow as the CLI: product create/status/config, environment list/create/use, billing strategy set, meter add, feature add, plan add, transition preview, and apply. Every tool accepts optional product and env fields where relevant and returns secret-free JSON.

farthershore set-key [token]

Set your API token. Interactive when run in a terminal, or pass the token as an argument for scripts.

farthershore whoami

Show your current authentication context (organization, auth method).

farthershore logout

Clear stored credentials.

farthershore set-url <url>

Override the API base URL (persisted in ~/.farthershore/config.json).

farthershore reset-url

Reset the API base URL to the default (https://core.farthershore.com).

Agent Workflow

The CLI is designed for AI agents to create and configure API products:

# 1. Agent receives: create a weather API product
farthershore init weather-api --format json

# 2. Agent clones the repo
git clone https://github.com/org/weather-api.git
cd weather-api

# 3. Agent reads AGENTS.md for configuration reference
cat AGENTS.md

# 4. Agent validates locally before pushing
farthershore validate

# 5. Agent pushes — product goes live automatically on valid config
git add -A && git commit -m "Configure product" && git push

Agents can also complete the flow entirely through API-backed CLI commands:

farthershore auth set-key "$FARTHERSHORE_TOKEN"
farthershore product create weather-api \
  --base-url https://api.example.com \
  --strategy prepaid_credits \
  --format json
farthershore meter add ai_tokens \
  --selector model \
  --measure input_tokens \
  --measure output_tokens \
  --rating provider_catalog \
  --catalog llm_models \
  --format json
farthershore feature add chat_completions \
  --route POST:/v1/chat/completions \
  --format json
farthershore plan add free \
  --free \
  --limit ai_tokens:month:100000:enforce \
  --feature chat_completions \
  --format json
farthershore plan add pro \
  --price-monthly 2900 \
  --credits-monthly-micros 500000000 \
  --meter ai_tokens \
  --feature chat_completions \
  --format json
farthershore draft validate --format json
farthershore transition preview --format json
farthershore apply --dry-run --format json
farthershore apply --format json
farthershore product status --format json

Global Flags

| Flag | Description | | ----------------- | ------------------------------------ | | --token <token> | Override auth token for this command | | --api-url <url> | Override API base URL | | --format json | Output as JSON (default for non-TTY) | | --version | Show version | | --help | Show help |

Environment Variables

| Variable | Description | | ---------------------- | ------------------------------------------------------- | | FARTHERSHORE_TOKEN | API token (overrides stored credentials) | | FARTHERSHORE_API_URL | API base URL (default: https://core.farthershore.com) |

Errors and exit codes

The CLI exits 0 on success and 1 on any failure (including commander-level argument errors). When the API returns a 4XX/5XX, the CLI prints the canonical error code in brackets and a one-line remediation hint when one is registered:

Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.

The bracketed code is stable across releases — quote it in support threads.

farthershore whoami --format json emits a stable JSON shape suitable for CI scripts. On the not-authenticated path it emits { "authenticated": false } with exit code 1.

CI / agent usage

The CLI is non-interactive whenever a token is available via the --token flag or FARTHERSHORE_TOKEN env var — set-key only prompts when stdin is a TTY and no token argument was passed, so it's safe to script. validate and apply emit GitHub Actions-formatted annotations when run under CI / GITHUB_ACTIONS.