feat: add global CLI options and environment variable support (#5)

Add --no-color, --quiet, --mode/--live/--sandbox flags and env var
support for --json (MEMBERSTACK_JSON) and --mode (MEMBERSTACK_MODE).
Replaces the boolean --live flag with a --mode <mode> option while
maintaining backwards compatibility via --live and --sandbox shorthands.
Disables cli-table3 ANSI codes when color is off. Updates docs and adds
comprehensive tests.

Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>

Author: bensabic

AGENTS.md

@@ -6,6 +6,7 @@ This file provides guidance to AI agents when working with code in this reposito
 
 ```bash
 pnpm build            # Build CLI with tsup (output: dist/)
+pnpm dev              # Run CLI from source via tsx (e.g. pnpm dev -- members list)
 pnpm test             # Run all tests with vitest
 pnpm check            # Lint and format check (Biome via ultracite)
 pnpm fix              # Auto-fix lint and format issues
@@ -41,4 +42,5 @@ Write code that is **accessible, performant, type-safe, and maintainable**. Focu
 ## Resources
 
 [ARCHITECTURE.md](./ARCHITECTURE.md): Detailed Project Architecture
-[CONTRIBUTING.md](.github/CONTRIBUTING.md): Project Contribution Guidelines
+[CONTRIBUTING.md](.github/CONTRIBUTING.md): Project Contribution Guidelines
+[Memberstack CLI Documentation](https://memberstack-cli.flashbrew.digital/llms.txt): Memberstack CLI Documentation

ARCHITECTURE.md

@@ -50,7 +50,10 @@ memberstack-cli/
 │   └── core/                   # Core library tests
 │       ├── auth.test.ts
 │       ├── graphql-client.test.ts
+│       ├── no-color.test.ts
 │       ├── oauth.test.ts
+│       ├── program-options.test.ts
+│       ├── quiet.test.ts
 │       └── utils.test.ts
 │
 ├── dist/                       # Compiled output (ESM)
@@ -64,14 +67,17 @@ memberstack-cli/
 
 ### Entry Point (`src/index.ts`)
 
-Prints the ASCII banner to stderr, registers all command groups on the shared `program` instance, and calls `parseAsync()`.
+Propagates `--no-color` / `NO_COLOR` to all color libraries before imports, conditionally prints the ASCII banner (suppressed by `--quiet`), registers all command groups on the shared `program` instance, and calls `parseAsync()`.
 
 ### Program (`src/lib/program.ts`)
 
-A shared Commander instance with two global options:
+A shared Commander instance with global options:
 
-- `--json` — output raw JSON instead of formatted tables
-- `--live` — use live environment instead of sandbox (appended as `?mode=live` or `?mode=sandbox` to the GraphQL URL)
+- `-j, --json` — output raw JSON instead of formatted tables (env: `MEMBERSTACK_JSON`)
+- `-q, --quiet` — suppress banner and non-essential output
+- `--no-color` — disable color output (respects the `NO_COLOR` standard)
+- `--mode <mode>` — set environment mode: `sandbox` (default) or `live` (env: `MEMBERSTACK_MODE`)
+- `--live` / `--sandbox` — shorthands for `--mode live` and `--mode sandbox`
 
 ### Commands (`src/commands/`)
 
@@ -118,7 +124,7 @@ Tokens are stored in `~/.memberstack/auth.json` with restrictive file permission
 - `printTable()` — renders data as a `cli-table3` table to stderr (or JSON to stdout with `--json`)
 - `printRecord()` — renders a single object as a vertical key-value table
 - `printJson()` — writes raw JSON to stdout
-- `printSuccess()` / `printError()` — colored status messages to stderr
+- `printSuccess()` / `printError()` — colored status messages to stderr (`printSuccess` is suppressed by `--quiet`)
 - `parseKeyValuePairs()` — parses `key=value` strings for `--data` options
 - `parseWhereClause()` — parses `field operator value` filter syntax for `--where`
 - `parseJsonString()` — parses raw JSON strings for `--query`
@@ -154,7 +160,7 @@ All user-facing output (tables, spinners, messages) goes to **stderr**. JSON out
 | `open` | Opens browser for OAuth login |
 | `papaparse` | CSV parsing and generation |
 
-Dev: `tsup` (bundler), `typescript`, `vitest` (tests), `biome` via `ultracite` (lint/format).
+Dev: `tsup` (bundler), `tsx` (dev runner), `typescript`, `vitest` (tests), `biome` via `ultracite` (lint/format).
 
 ## Build & CI
 

README.md

@@ -42,106 +42,30 @@ memberstack skills add memberstack-cli
 
 ### Global Options
 
-| Option | Description |
-|---|---|
-| `--json` | Output raw JSON instead of formatted tables |
-| `--live` | Use live environment instead of sandbox |
+| Option | Env Var | Description |
+|---|---|---|
+| `-j, --json` | `MEMBERSTACK_JSON` | Output raw JSON instead of formatted tables |
+| `-q, --quiet` | | Suppress banner and non-essential output |
+| `--no-color` | `NO_COLOR` | Disable color output (respects the [NO_COLOR standard](https://no-color.org)) |
+| `--mode <mode>` | `MEMBERSTACK_MODE` | Set environment mode (`sandbox` or `live`, default: `sandbox`) |
+| `--live` | | Shorthand for `--mode live` |
+| `--sandbox` | | Shorthand for `--mode sandbox` |
 
 ### Commands
 
-#### `auth` — Authentication
-
-| Subcommand | Description |
-|---|---|
-| `login` | Authenticate with Memberstack via OAuth |
-| `logout` | Remove stored authentication tokens |
-| `status` | Show current authentication status |
-
-#### `whoami` — Identity
-
-Show the current authenticated app and user.
-
-#### `apps` — App Management
-
-| Subcommand | Description |
-|---|---|
-| `current` | Show the current app |
-| `create` | Create a new app |
-| `update` | Update the current app |
-| `delete` | Delete an app |
-| `restore` | Restore a deleted app |
-
-#### `members` — Member Management
-
-| Subcommand | Description |
-|---|---|
-| `list` | List members (with pagination) |
-| `get <id_or_email>` | Get a member by ID or email |
-| `create` | Create a new member |
-| `update <id>` | Update a member |
-| `delete <id>` | Delete a member |
-| `add-plan <id>` | Add a free plan to a member |
-| `remove-plan <id>` | Remove a free plan from a member |
-| `count` | Show total member count |
-| `find` | Find members by field values or plan |
-| `stats` | Show member statistics |
-| `export` | Export all members to CSV or JSON |
-| `import` | Import members from a CSV or JSON file |
-| `bulk-update` | Bulk update members from a file |
-| `bulk-add-plan` | Add a plan to multiple members |
-
-#### `plans` — Plan Management
-
-| Subcommand | Description |
-|---|---|
-| `list` | List all plans |
-| `get <id>` | Get a plan by ID |
-| `create` | Create a new plan |
-| `update <id>` | Update a plan (name, status, redirects, permissions, etc.) |
-| `delete <id>` | Delete a plan |
-| `order` | Reorder plans by priority |
-
-#### `tables` — Data Table Management
-
-| Subcommand | Description |
+| Command | Functionality |
 |---|---|
-| `list` | List all data tables |
-| `get <table_key>` | Get a data table by key or ID |
-| `describe <table_key>` | Show table schema and access rules |
-| `create` | Create a new data table |
-| `update <id>` | Update a data table |
-| `delete <id>` | Delete a data table |
-
-#### `records` — Record Management
-
-| Subcommand | Description |
-|---|---|
-| `create <table_key>` | Create a new record |
-| `update <table_key> <record_id>` | Update a record |
-| `delete <table_key> <record_id>` | Delete a record |
-| `query <table_key>` | Query records with a JSON filter |
-| `count <table_key>` | Count records in a table |
-| `find <table_key>` | Find records with friendly filter syntax |
-| `export <table_key>` | Export all records to CSV or JSON |
-| `import <table_key>` | Import records from a CSV or JSON file |
-| `bulk-update` | Bulk update records from a file |
-| `bulk-delete <table_key>` | Bulk delete records matching a filter |
-
-#### `custom-fields` — Custom Field Management
-
-| Subcommand | Description |
-|---|---|
-| `list` | List all custom fields |
-| `create` | Create a custom field |
-| `update <id>` | Update a custom field |
-| `delete <id>` | Delete a custom field |
-
-#### `skills` — Agent Skill Management
-
-| Subcommand | Description |
-|---|---|
-| `add <skill>` | Add a Memberstack agent skill |
-| `remove <skill>` | Remove a Memberstack agent skill |
+| `auth` | Login, logout, and check authentication status |
+| `whoami` | Show current authenticated app and user |
+| `apps` | View, create, update, delete, and restore apps |
+| `members` | List, create, update, delete, import/export, bulk ops |
+| `plans` | List, create, update, delete, and reorder plans |
+| `tables` | List, create, update, delete, and describe schema |
+| `records` | CRUD, query, import/export, bulk ops |
+| `custom-fields` | List, create, update, and delete custom fields |
+| `skills` | Add/remove agent skills for Claude Code and Codex |
+
+For full command details and usage, see the [Command Reference](https://memberstack-cli.flashbrew.digital/docs/commands).
 
 ## Examples
 
@@ -162,6 +86,7 @@ memberstack members export --format csv --output members.csv
 memberstack records import my_table --file data.json
 
 # Use live environment
+memberstack members list --mode live
 memberstack members list --live
 ```
 
@@ -171,6 +96,9 @@ memberstack members list --live
 # Install dependencies
 pnpm install
 
+# Run locally (via tsx, no build needed)
+pnpm dev -- members list --json
+
 # Build
 pnpm build
 

package.json

@@ -49,6 +49,7 @@
   "packageManager": "pnpm@10.29.3",
   "scripts": {
     "build": "tsup",
+    "dev": "tsx src/index.ts",
     "test": "vitest run",
     "type-check": "tsc --noEmit",
     "check": "ultracite check",
@@ -70,6 +71,7 @@
     "@types/papaparse": "^5.5.2",
     "lint-staged": "^16.2.7",
     "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "ultracite": "7.2.3",
     "vitest": "^4.0.18"