@farthershore/cli 0.3.8 → 0.3.9

package/dist/commands/apply.js

@@ -223,6 +223,17 @@ export function registerApplyCommand(program, getClient) {
         "Automatically scopes to the current git branch so env branches compile against their own plans.")
         .option("--branch <branch>", "Override the branch used for env-scoped compilation (default: auto-detected)")
         .option("--dry-run", "Run local validation and remote compile without applying product state")
+        .addHelpText("after", `
+Agent notes:
+  apply first validates local product.yaml when it matches the target product, then asks core to compile the pushed branch state.
+  Unpushed local edits are not included in remote compile. Push or use CLI config commands for API-backed changes.
+  Use --format json for stable output: ok, success, errors, warnings, nextActions.
+
+Examples:
+  farthershore apply --dry-run --format json
+  farthershore apply my-weather-api --dry-run --format json
+  farthershore apply my-weather-api --branch feature/billing-change --dry-run --format json
+`)
         .action(async (productArg, opts) => {
         const client = getClient();
         const globalFormat = program.opts().format;

package/dist/commands/billing.js

@@ -1,10 +1,34 @@
 import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
 export function registerBillingCommands(program, getClient) {
-    const billing = program.command("billing").description("Manage billing");
-    const strategy = billing.command("strategy").description("Billing strategy");
+    const billing = program
+        .command("billing")
+        .description("Manage product-level billing strategy and transition policy")
+        .addHelpText("after", `
+Agent notes:
+  Billing strategy is product-level for paid plans. Paid plans should not mix strategies.
+  Strategies: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits.
+  Subscriber actions: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only.
+
+Examples:
+  farthershore billing strategy get --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
+`);
+    const strategy = billing
+        .command("strategy")
+        .description("Get or set the product-level billing strategy")
+        .addHelpText("after", `
+Examples:
+  farthershore billing strategy get --format json
+  farthershore billing strategy set subscription_overage --format json
+`);
     strategy
         .command("get")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore billing strategy get --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -18,9 +42,14 @@ export function registerBillingCommands(program, getClient) {
     strategy
         .command("set <strategy>")
         .option("--product <product>", "Product id or name")
-        .option("--transition <action>", "Default subscriber transition action", "preserve_current_period")
+        .option("--transition <action>", "Default subscriber transition action: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only", "preserve_current_period")
         .option("--proration <mode>", "Proration mode", "none")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore billing strategy set prepaid_credits --transition preserve_current_period --format json
+  farthershore billing strategy set pay_as_you_go --dry-run --format json
+`)
         .action(async (nextStrategy, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -36,12 +65,23 @@ export function registerBillingCommands(program, getClient) {
             message: "Billing strategy updated",
         });
     });
-    billing
-        .command("policy set")
+    const policy = billing
+        .command("policy")
+        .description("Set subscriber change policy defaults")
+        .addHelpText("after", `
+Example:
+  farthershore billing policy set --default preserve_current_period --proration none --format json
+`);
+    policy
+        .command("set")
         .option("--product <product>", "Product id or name")
-        .option("--default <action>", "Default subscriber action", "preserve_current_period")
+        .option("--default <action>", "Default subscriber action: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only", "preserve_current_period")
         .option("--proration <mode>", "Proration mode", "none")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore billing policy set --default preserve_current_period --proration none --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/feature.js

@@ -1,9 +1,25 @@
 import { findPlan, loadAcceptedSpec, objectAt, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
 export function registerFeatureCommands(program, getClient) {
-    const feature = program.command("feature").description("Manage features");
+    const feature = program
+        .command("feature")
+        .description("Manage route-bound product features")
+        .addHelpText("after", `
+Agent notes:
+  Features gate routes. Add a feature with one or more METHOD:/path routes, then bind it to plans.
+  Use METHOD:* only when the feature should cover all methods for a path.
+
+Examples:
+  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
+  farthershore feature bind chat_completions --plan pro --format json
+  farthershore feature list --format json
+`);
     feature
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore feature list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -19,6 +35,11 @@ export function registerFeatureCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .option("--route <route>", "Route binding METHOD:/path; repeatable", collect, [])
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
+  farthershore feature add weather_read --route GET:/v1/weather --route GET:/v1/forecast --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -35,6 +56,10 @@ export function registerFeatureCommands(program, getClient) {
         .requiredOption("--plan <plan>", "Plan key")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore feature bind chat_completions --plan pro --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -53,6 +78,10 @@ export function registerFeatureCommands(program, getClient) {
         .requiredOption("--plan <plan>", "Plan key")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore feature unbind chat_completions --plan starter --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/login.js

@@ -4,10 +4,25 @@ import { loadConfig, saveConfig, saveCredentials, clearCredentials, } from "../c
 import { resolveToken } from "../auth.js";
 import * as output from "../output.js";
 export function registerAuthCommands(program) {
-    const auth = program.command("auth").description("Manage authentication");
+    const auth = program
+        .command("auth")
+        .description("Manage authentication")
+        .addHelpText("after", `
+Agent notes:
+  Prefer FARTHERSHORE_TOKEN in CI/agent environments. Use auth set-key for local persistent credentials.
+
+Examples:
+  farthershore auth set-key "$FARTHERSHORE_TOKEN"
+  farthershore whoami --format json
+`);
     auth
         .command("set-key [token]")
         .description("Set your API token")
+        .addHelpText("after", `
+Examples:
+  farthershore auth set-key mk_xxx
+  farthershore auth set-key "$FARTHERSHORE_TOKEN"
+`)
         .action(async (tokenArg) => {
         await setKey(tokenArg);
     });

package/dist/commands/meter.js

@@ -1,9 +1,25 @@
 import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
 export function registerMeterCommands(program, getClient) {
-    const meter = program.command("meter").description("Manage usage meters");
+    const meter = program
+        .command("meter")
+        .description("Manage product usage meters and rating sources")
+        .addHelpText("after", `
+Agent notes:
+  Meters define what usage is measured. Plans reference meters; plans do not define provider-specific rates.
+  Rating sources: fixed, provider_catalog, upstream_reported, external_rate_api, custom.
+
+Examples:
+  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter add requests --measure count --rating fixed --format json
+  farthershore meter list --format json
+`);
     meter
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore meter list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -20,12 +36,18 @@ export function registerMeterCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .option("--selector <field>", "Selector field, for example model")
         .option("--measure <measure>", "Measure name; repeatable", collect, [])
-        .option("--rating <source>", "Rating source", "fixed")
+        .option("--rating <source>", "Rating source: fixed, provider_catalog, upstream_reported, external_rate_api, custom", "fixed")
         .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
         .option("--resolver <resolver>", "Resolver id for external/custom rating")
         .option("--amount-field <path>", "Amount field for upstream_reported rating")
         .option("--currency-field <path>", "Currency field for upstream_reported rating")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter add requests --measure count --rating fixed --dry-run --format json
+  farthershore meter add upstream_cost --measure cost_micros --rating upstream_reported --amount-field usage.cost_micros --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -45,12 +67,17 @@ export function registerMeterCommands(program, getClient) {
     meter
         .command("rating set <key>")
         .option("--product <product>", "Product id or name")
-        .requiredOption("--rating <source>", "Rating source")
+        .requiredOption("--rating <source>", "Rating source: fixed, provider_catalog, upstream_reported, external_rate_api, custom")
         .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
         .option("--resolver <resolver>", "Resolver id for external/custom rating")
         .option("--amount-field <path>", "Amount field for upstream_reported rating")
         .option("--currency-field <path>", "Currency field for upstream_reported rating")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore meter rating set ai_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter rating set upstream_cost --rating upstream_reported --amount-field usage.cost_micros --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/plan.js

@@ -1,9 +1,27 @@
 import { findPlan, loadAcceptedSpec, plans, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
 export function registerPlanCommands(program, getClient) {
-    const plan = program.command("plan").description("Manage product plans");
+    const plan = program
+        .command("plan")
+        .description("Manage free and paid plans in the accepted product config")
+        .addHelpText("after", `
+Agent notes:
+  Plans are keyed by plan name/key, not by usage type.
+  Only one free plan is allowed. Free plans should include a hard enforced limit.
+  Duplicate paid prices are rejected server-side. Use --dry-run before risky changes.
+  Limit format is meter:window:capacity:enforcement, for example ai_tokens:month:100000:enforce.
+
+Examples:
+  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 --format json
+`);
     plan
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore plan list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -25,6 +43,12 @@ export function registerPlanCommands(program, getClient) {
         .option("--feature <feature>", "Enabled feature; repeatable", collect, [])
         .option("--limit <limit>", "Limit meter:window:capacity:enforcement; repeatable", collect, [])
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  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 add starter --price-monthly 900 --meter requests --feature weather_read --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -47,6 +71,10 @@ export function registerPlanCommands(program, getClient) {
         .requiredOption("--monthly <cents>", "Monthly price in cents", parseInteger)
         .option("--currency <currency>", "Currency", "USD")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan set-price pro --monthly 4900 --dry-run --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.free = false;
@@ -63,6 +91,11 @@ export function registerPlanCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .requiredOption("--limit <limit>", "Limit meter:window:capacity:enforcement")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore plan set-limit free --limit ai_tokens:month:100000:enforce --format json
+  farthershore plan set-limit pro --limit ai_tokens:month:1000000:track --dry-run --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             const next = parseLimit(opts.limit);
@@ -82,6 +115,10 @@ export function registerPlanCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .requiredOption("--monthly-micros <micros>", "Monthly included credits", parseInteger)
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan set-credits pro --monthly-micros 500000000 --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.credits = { monthlyIncludedMicros: opts.monthlyMicros };
@@ -92,6 +129,10 @@ export function registerPlanCommands(program, getClient) {
         .argument("<feature>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan add-feature pro chat_completions --format json
+`)
         .action(async (key, feature, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             const features = stringArrayAt(plan, "features");
@@ -104,6 +145,10 @@ export function registerPlanCommands(program, getClient) {
         .argument("<feature>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan remove-feature starter chat_completions --dry-run --format json
+`)
         .action(async (key, feature, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.features = stringArrayAt(plan, "features").filter((candidate) => candidate !== feature);
@@ -113,6 +158,10 @@ export function registerPlanCommands(program, getClient) {
         .command("remove <key>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan remove starter --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/product.js

@@ -2,15 +2,38 @@ import { saveConfig } from "../config.js";
 import * as output from "../output.js";
 import { commandFormat, printResult, resolveProductId } from "./helpers.js";
 export function registerProductCommands(program, getClient) {
-    const product = program.command("product").description("Manage products");
+    const product = program
+        .command("product")
+        .description("Manage products and inspect the latest accepted internal product config")
+        .addHelpText("after", `
+Agent notes:
+  Product commands use core APIs, not local files. After product create, the product is selected in ~/.farthershore/config.json.
+  GitHub, UI, and CLI edits are proposals. product config/status read the accepted internal config.
+
+Examples:
+  farthershore product create weather-api --base-url https://api.example.com --strategy prepaid_credits --format json
+  farthershore product status --format json
+  farthershore product config --format yaml
+  farthershore product attempts --format json
+`);
     product
         .command("create <name>")
-        .description("Create a product and select it for subsequent CLI commands")
+        .description("Create a product, initialize accepted config, and select it for later commands")
         .requiredOption("--base-url <url>", "Backend API base URL")
-        .option("--strategy <strategy>", "Product billing strategy", "flat_subscription")
+        .option("--strategy <strategy>", "Product billing strategy: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits", "flat_subscription")
         .option("--description <desc>", "Product description")
         .option("--display-name <name>", "Display name")
         .option("--dry-run", "Print the create request without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore product create weather-api --base-url https://api.example.com --format json
+  farthershore product create ai-gateway --base-url https://api.example.com --strategy prepaid_credits --format json
+
+Next commands:
+  farthershore meter add --help
+  farthershore feature add --help
+  farthershore plan add --help
+`)
         .action(async (name, opts) => {
         if (opts.dryRun) {
             printResult(program, "Product create dry run", {
@@ -64,6 +87,10 @@ export function registerProductCommands(program, getClient) {
         .command("status")
         .description("Show selected product status")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore product status --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -76,9 +103,14 @@ export function registerProductCommands(program, getClient) {
     });
     product
         .command("config")
-        .description("Show latest accepted internal product config")
+        .description("Show latest accepted internal product config as json or yaml")
         .option("--product <product>", "Product id or name")
         .option("--format <format>", "Output format: json or yaml")
+        .addHelpText("after", `
+Examples:
+  farthershore product config --format json
+  farthershore product config --format yaml
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -93,6 +125,10 @@ export function registerProductCommands(program, getClient) {
         .command("attempts")
         .description("Show rejected product config attempts")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore product attempts --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/transition.js

@@ -7,13 +7,30 @@ import { analyzePlanTransition } from "./plan-transition.js";
 export function registerTransitionCommands(program, getClient) {
     const transition = program
         .command("transition")
-        .description("Preview subscriber impact for product config changes");
+        .description("Preview subscriber impact for product config changes")
+        .addHelpText("after", `
+Agent notes:
+  New subscribers use accepted config immediately. Existing subscribers follow billing.subscriberChangePolicy.
+  Preview before price, feature, limit, credit, rating, or strategy changes.
+
+Examples:
+  farthershore transition preview --format json
+  farthershore transition preview --to product.yaml --format json
+`);
     transition
         .command("preview")
         .description("Compare the latest accepted config to a proposed config and show subscriber transition impact")
         .option("--product <product>", "Product id or name")
         .option("--to <file>", "Proposed product YAML file")
         .option("--format <format>", "Output format: table or json")
+        .addHelpText("after", `
+Examples:
+  farthershore transition preview --format json
+  farthershore transition preview --to product.yaml --format json
+
+Output includes:
+  ok, productId, transitionPreview, errors, warnings, nextActions
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/validate.js

@@ -170,7 +170,17 @@ function reportValidationResult(result) {
 export function registerValidateCommand(program) {
     program
         .command("validate [file]")
-        .description("Validate a local product.yaml file")
+        .description("Validate a local product.yaml file without API calls")
+        .addHelpText("after", `
+Agent notes:
+  Use validate before committing product.yaml changes. This is local schema validation only.
+  Use apply --dry-run for remote compiler validation against pushed branch state.
+
+Examples:
+  farthershore validate
+  farthershore validate product.yaml
+  farthershore apply --dry-run --format json
+`)
         // Action body is sync; commander only requires a thenable on
         // .action when await is used. Drop `async` keyword.
         .action((file) => {

package/dist/index.js

@@ -24,11 +24,38 @@ const pkg = JSON.parse(await readFile(join(__dirname, "..", "package.json"), "ut
 const program = new Command();
 program
     .name("farthershore")
-    .description("FartherShore CLI — create and manage API products")
+    .description("FartherShore CLI — agent-friendly commands to create, configure, validate, and launch API products")
     .version(pkg.version)
     .option("--token <token>", "Override auth token")
     .option("--api-url <url>", "Override API base URL")
-    .option("--format <format>", "Output format: table, json");
+    .option("--format <format>", "Output format. Use --format json for stable machine-readable agent output")
+    .addHelpText("after", `
+Agent discovery:
+  Start with:
+    farthershore --help
+    farthershore product --help
+    farthershore meter add --help
+    farthershore feature add --help
+    farthershore plan add --help
+    farthershore transition preview --help
+    farthershore apply --help
+
+Agent end-to-end API workflow:
+  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 transition preview --format json
+  farthershore apply --dry-run --format json
+  farthershore product status --format json
+
+Useful constants:
+  Billing strategies: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits
+  Rating sources: fixed, provider_catalog, upstream_reported, external_rate_api, custom
+  Transition actions: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only
+`);
 // Lazy client — created on first use with resolved auth
 function getClient() {
     const config = loadConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "FartherShore CLI — create and configure API products",
   "type": "module",
   "bin": {