@godaddy/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,400 +1,101 @@
 # GoDaddy CLI
 
-A powerful command-line interface for interacting with GoDaddy's developer ecosystem. Manage your applications, handle authentication, and work with webhooks effortlessly.
+Agent-first CLI for interacting with GoDaddy Developer Platform.
 
 ## Installation
 
 ```bash
-# Install the CLI globally from npm
 npm install -g @godaddy/cli
-
-# Verify installation
 godaddy --help
 ```
 
-## Development
+## Output Contract
 
-```bash
-# Watch mode for development using tsx
-pnpm tsx --watch index.ts
+All executable commands emit JSON envelopes:
 
-# Quick command execution during development
-pnpm tsx src/index.tsx application <command>
+```json
+{"ok":true,"command":"godaddy env get","result":{"environment":"ote"},"next_actions":[...]}
 ```
 
-## Features
-
-- **Application Management**: Create, view, and release applications
-- **Authentication**: Secure OAuth-based authentication with GoDaddy
-- **Webhook Management**: List available webhook event types
-- **Environment Management**: Work across different GoDaddy environments
-- **Actions Management**: List and describe available application actions
-
-## Command Reference
-
-### Global Options
-
-```bash
-godaddy --help                       # Display help information
-godaddy --version                    # Display version information
-godaddy -e, --env <environment>      # Set target environment (ote, prod)
-godaddy --debug                      # Enable debug logging for HTTP requests and responses
+```json
+{"ok":false,"command":"godaddy application info demo","error":{"message":"Application 'demo' not found","code":"NOT_FOUND"},"fix":"Use discovery commands such as: godaddy application list or godaddy actions list.","next_actions":[...]}
 ```
 
-### Environment Commands
-
-```bash
-# List all available environments
-godaddy env list
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
+`--help` remains standard CLI help text.
+`--output` has been removed; all executable command paths return JSON envelopes.
+Use `--pretty` to format envelopes with 2-space indentation for human readability.
+Long-running operations can stream typed NDJSON events with `--follow`, ending with a terminal `result` or `error` event.
 
-# Get current environment details
-godaddy env get
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Switch to a different environment
-godaddy env set <environment>        # <environment> is one of: ote, prod
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# View detailed environment configuration
-godaddy env info [environment]       # [environment] is one of: ote, prod (defaults to current)
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-```
-
-### Authentication Commands
+## Root Discovery
 
 ```bash
-# Login to GoDaddy Developer Platform
-godaddy auth login                   # Opens browser for OAuth authentication
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Logout and clear stored credentials
-godaddy auth logout
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Check current authentication status
-godaddy auth status
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
+godaddy
 ```
 
-### Application Commands
-
-> **Note**: `godaddy app` can be used as a shorthand alias for `godaddy application`
-
-```bash
-# List all applications
-godaddy application list             # Alias: godaddy app ls
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Show application information
-godaddy application info <name>      # Shows info for the named application
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Initialize a new application
-godaddy application init
-  Options:
-    --name <name>                    # Application name
-    --description <description>      # Application description
-    --url <url>                      # Application URL
-    --proxy-url <proxyUrl>           # Proxy URL for API endpoints
-    --scopes <scopes>                # Authorization scopes (space-separated)
-    -c, --config <path>              # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
+Returns environment/auth snapshots and the full command tree.
 
-# Validate application configuration
-godaddy application validate <name>
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
+## Global Options
 
-# Update existing application
-godaddy application update <name>
-  Options:
-    --label <label>                  # Application label
-    --description <description>      # Application description
-    --status <status>                # Application status (ACTIVE|INACTIVE)
-    -o, --output <format>            # Output format: json or text (default: text)
+- `-e, --env <environment>`: validate target environment (`ote`, `prod`)
+- `--debug`: enable debug logging (stderr only)
+- `--pretty`: pretty-print JSON envelopes (2-space indentation)
 
-# Create a new release of your application
-godaddy application release <name>
-  Options:
-    --release-version <version>      # Release version (required)
-    --description <description>      # Release description
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
+## Commands
 
-# Deploy your application to the platform
-godaddy application deploy <name>
-  Options:
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
+### Environment
 
-# Enable an application on a store
-godaddy application enable <name>
-  Options:
-    --store-id <storeId>             # Store ID (required)
-    -o, --output <format>            # Output format: json or text (default: text)
+- `godaddy env`
+- `godaddy env list`
+- `godaddy env get`
+- `godaddy env set <environment>`
+- `godaddy env info [environment]`
 
-# Disable an application on a store
-godaddy application disable <name>
-  Options:
-    --store-id <storeId>             # Store ID (required)
-    -o, --output <format>            # Output format: json or text (default: text)
+### Authentication
 
-# Archive an application
-godaddy application archive <name>
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
+- `godaddy auth`
+- `godaddy auth login`
+- `godaddy auth logout`
+- `godaddy auth status`
 
-# Add components to your application
-godaddy application add <type>
-  <type> can be one of:              # action, subscription, extension
-```
+### Application
 
-#### Adding Actions
-
-```bash
-godaddy application add action
-  Options:
-    --name <name>                    # Action name (required)
-    --url <url>                      # Action endpoint URL (required)
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
-```
+- `godaddy application` (alias: `godaddy app`)
+- `godaddy application list` (alias: `godaddy app ls`)
+- `godaddy application info <name>`
+- `godaddy application validate <name>`
+- `godaddy application update <name> [--label <label>] [--description <description>] [--status <status>]`
+- `godaddy application enable <name> --store-id <storeId>`
+- `godaddy application disable <name> --store-id <storeId>`
+- `godaddy application archive <name>`
+- `godaddy application init [--name <name>] [--description <description>] [--url <url>] [--proxy-url <proxyUrl>] [--scopes <scopes>] [--config <path>] [--environment <env>]`
+- `godaddy application release <name> --release-version <version> [--description <description>] [--config <path>] [--environment <env>]`
+- `godaddy application deploy <name> [--config <path>] [--environment <env>] [--follow]`
 
-#### Adding Subscriptions
+#### Application Add
 
-```bash
-godaddy application add subscription
-  Options:
-    --name <name>                    # Subscription name (required)
-    --events <events>                # Comma-separated list of events (required)
-    --url <url>                      # Webhook endpoint URL (required)
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
-```
+- `godaddy application add`
+- `godaddy application add action --name <name> --url <url>`
+- `godaddy application add subscription --name <name> --events <events> --url <url>`
+- `godaddy application add extension`
+- `godaddy application add extension embed --name <name> --handle <handle> --source <source> --target <targets>`
+- `godaddy application add extension checkout --name <name> --handle <handle> --source <source> --target <targets>`
+- `godaddy application add extension blocks --source <source>`
 
-#### Adding Extensions
+### Webhooks
 
-```bash
-# Add an embed extension (injected UI at specific page locations)
-godaddy application add extension embed
-  Options:
-    --name <name>                    # Extension name (required)
-    --handle <handle>                # Extension handle/unique identifier (required)
-    --source <source>                # Path to extension source file (required)
-    --target <targets>               # Comma-separated list of target locations (required)
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
+- `godaddy webhook`
+- `godaddy webhook events`
 
-# Add a checkout extension (checkout flow UI)
-godaddy application add extension checkout
-  Options:
-    --name <name>                    # Extension name (required)
-    --handle <handle>                # Extension handle/unique identifier (required)
-    --source <source>                # Path to extension source file (required)
-    --target <targets>               # Comma-separated list of checkout target locations (required)
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
+### Actions
 
-# Set the blocks extension source (consolidated UI blocks package)
-godaddy application add extension blocks
-  Options:
-    --source <source>                # Path to blocks extension source file (required)
-    --config <path>                  # Path to configuration file
-    --environment <env>              # Environment (ote|prod)
-    -o, --output <format>            # Output format: json or text (default: text)
-```
-
-### Webhook Commands
-
-```bash
-# List available webhook event types
-godaddy webhook events               # Lists all available webhook event types you can subscribe to
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-```
-
-### Actions Commands
-
-```bash
-# List all available actions
-godaddy actions list                 # Lists all available actions an application can hook into
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-
-# Show detailed interface information for a specific action
-godaddy actions describe <action>    # Displays request/response schemas for the action
-  Options:
-    -o, --output <format>            # Output format: json or text (default: text)
-```
+- `godaddy actions`
+- `godaddy actions list`
+- `godaddy actions describe <action>`
 
-#### Available Actions
-
-The following actions are available for applications to hook into:
-
-- `location.address.verify` - Verify and standardize a physical address
-- `commerce.taxes.calculate` - Calculate taxes for a purchase
-- `commerce.shipping-rates.calculate` - Calculate shipping rates
-- `commerce.price-adjustment.apply` - Apply price adjustments
-- `commerce.price-adjustment.list` - List price adjustments
-- `notifications.email.send` - Send email notifications
-- `commerce.payment.get` - Get payment details
-- `commerce.payment.cancel` - Cancel a payment
-- `commerce.payment.refund` - Refund a payment
-- `commerce.payment.process` - Process a payment
-- `commerce.payment.auth` - Authorize a payment
-
-## Automation Examples
-
-### Complete Application Setup
-
-Create and configure an application without interactive prompts:
+## Development
 
 ```bash
-# Create application
-godaddy application init \
-  --name "my-ecommerce-app" \
-  --description "Advanced e-commerce integration" \
-  --url "https://app.mystore.com" \
-  --proxy-url "https://api.mystore.com" \
-  --scopes "domains orders customers" \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json \
-  --env prod
-
-# Add action
-godaddy application add action \
-  --name "order.completed" \
-  --url "https://api.mystore.com/actions/order-completed" \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json
-
-# Add webhook subscription
-godaddy application add subscription \
-  --name "order-events" \
-  --events "order.created,order.completed,order.cancelled" \
-  --url "https://api.mystore.com/webhooks/orders" \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json
-
-# Add embed extension
-godaddy application add extension embed \
-  --name "my-widget" \
-  --handle "my-widget-handle" \
-  --source "./extensions/embed/index.tsx" \
-  --target "body.end" \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json
-
-# Create a release
-godaddy application release my-ecommerce-app \
-  --release-version "1.0.0" \
-  --description "Initial release" \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json
-
-# Deploy the application
-godaddy application deploy my-ecommerce-app \
-  --config ./config/godaddy.prod.toml \
-  --environment prod \
-  --output json
-
-# Enable on a store
-godaddy application enable my-ecommerce-app \
-  --store-id "12345" \
-  --output json
+pnpm install
+pnpm run build
+pnpm test
 ```
-
-## Environment Management
-
-The CLI supports multiple GoDaddy environments:
-
-- **ote**: Pre-production environment that mirrors production
-- **prod**: Production environment for live applications
-
-You can specify the environment in two ways:
-
-1. Using the global `-e, --env` flag with any command: `godaddy application info my-app --env ote`
-2. Setting a default environment: `godaddy env set prod`
-
-Use `godaddy env info` to view detailed configuration for your current environment.
-
-## Application Configuration
-
-The CLI uses a configuration file (`godaddy.toml`) to store your application settings. You can provide a custom configuration file path using the `--config` option with commands that support it.
-
-Environment-specific configuration files can be used by naming them `godaddy.<environment>.toml` (e.g., `godaddy.dev.toml`).
-
-Example configuration:
-
-```toml
-name = "my-app"
-client_id = "your-client-id"
-description = "My GoDaddy Application"
-url = "https://myapp.example.com"
-proxy_url = "https://proxy.example.com"
-authorization_scopes = ["domains", "shopper"]
-version = "0.0.0"
-actions = []
-
-[[subscriptions.webhook]]
-name = "domain-events"
-events = ["example:v1:domain:created", "example:v1:domain:updated"]
-url = "https://myapp.example.com/webhooks"
-
-[extensions]
-ui_extension = "value"
-
-[dependencies]
-app = [{name = "required-app", version = "^1.0.0"}]
-feature = [{name = "required-feature"}]
-```
-
-## Application Deployment
-
-The deployment process consists of several steps:
-
-1. **Initialize**: Create your application with `godaddy application init`
-2. **Configure**: Add components with the `application add` commands
-3. **Validate**: Ensure your configuration is valid with `godaddy application validate`
-4. **Release**: Create a new version with `godaddy application release`
-5. **Deploy**: Deploy your application with `godaddy application deploy`
-6. **Enable**: Enable your application on stores with `godaddy application enable`
-
-## Authentication
-
-Authentication is handled securely using OAuth. The CLI will:
-
-1. Open a browser for authentication with GoDaddy
-2. Store tokens securely in your system keychain
-3. Automatically use the stored token for future commands
-
-## Requirements
-
-- Node.js 16+
-- Access to GoDaddy Developer Account
-
-## License
-
-Copyright GoDaddy Inc. All rights reserved.