@api-now/cli 1.9.0 → 1.11.0

package/README.md

@@ -1,6 +1,6 @@
 # API NOW! CLI
 
-The **API NOW! CLI** is a robust, cross-platform command-line tool designed to manage settings, handle authentication, organize directories/files, and publish assets directly to the Data Catalog from your terminal.
+The **API NOW! CLI** is a robust, cross-platform command-line tool designed to manage settings, handle authentication, organize directories/files, validate and transition data domains, and publish assets directly to the Data Catalog from your terminal.
 
 ---
 
@@ -10,7 +10,9 @@ The **API NOW! CLI** is a robust, cross-platform command-line tool designed to m
 - **Interactive Onboarding**: Guided setup prompts for first-time users to configure organization names and slugs (validated against reserved keywords/taken values).
 - **Default Organization Management**: List organizations and pin a default workspace ID.
 - **Metadata and Media Uploads**: Create, list, and read blueprints, domains, and multimedia assets.
-- **Data Catalog Publishing**: Publish schemas and datasets to the global/private catalog with automatic semantic versioning support.
+- **Data Domain Management & Publishing**: Mutate data domains via declarative JSON patch diffing, transition data domain lifecycles (`draft`, `committed`, `published`), bump versions, run pre-publish validation, and publish domains directly to the Data Catalog.
+- **Local & Remote Schema Validation**: Validate Data Domain and API Model schemas from local files, STDIN, or directly from remote organization files.
+- **Data Catalog Publishing**: Publish schemas and datasets to the global/private catalog with automatic semantic versioning support, deprecation, and unpublishing.
 - **Developer Formatting Options**: Toggle outputs between human-friendly ASCII tables and machine-readable JSON.
 
 ---
@@ -30,45 +32,72 @@ Once installed, the CLI is available as the `apinow` command.
 ## Usage & Commands
 
 All commands support the following global options (which can be specified before or after any subcommand):
-- `--api-url <url>`: Override the target API Server URL (Default: `http://localhost:8080`). Note that the platform is actively under development and the final default URL will be set once the platform is officially released.
+
 - `--format <text|json>`: Define the output layout (Default: `text`).
-- `--debug`: Enable debug/verbose logging.
+- `--debug` / `-v, --verbose`: Enable debug/verbose logging.
 
 ### 1. Configuration (`config`)
-Read and write persistent CLI configurations stored in the OS settings folder depending on the platform:
+
+Read and manage CLI configurations stored in the OS settings folder depending on the platform:
+
 - **Linux**: `~/.config/apinow-cli/config.json` (or respects `$XDG_CONFIG_HOME`)
 - **macOS**: `~/Library/Preferences/apinow-cli/config.json`
 - **Windows**: `%APPDATA%\apinow-cli\config.json`
 
 > [!TIP]
-> **Local Project Configuration**:
-> The CLI and MCP server both support local project-level configuration overrides. If a file named `apinow.json` or `.apinowrc.json` is found in the current working directory or any parent directories, its settings are loaded and merged, with local keys overriding global config settings. This is useful for project-specific settings (like pointing to a local development API URL) without changing global config files.
+> **Local Project Configuration (Single Source of Truth)**:
+> When a file named `apinow.json` or `.apinowrc.json` is found in the current working directory or any parent directories, it is treated as the complete, authoritative single source of truth (SSOT) configuration for the project, replacing the global configuration. This allows project-local test environments with dedicated endpoints, tokens, or organizations without polluting your global configuration.
+>
+> Note that CLI write commands (such as `apinow auth login` and `apinow orgs set-default`) persist updates to your global configuration and will not modify tracked project files.
 
 ```bash
-# Get a configuration property (e.g. apiUrl, defaultOrg)
+# Get a configuration property (e.g. apiUrl, defaultOrg, activeProfile)
 apinow config get <key>
 
-# Set a configuration property
-apinow config set <key> <value>
+# Reset configuration to default values
+apinow config reset
 ```
 
 ### 2. Authentication (`auth`)
-Securely log in to the API platform using OAuth2.
+
+Securely log in to the API Now platform using OAuth2.
 
 ```bash
-# Log in using Google, GitHub, or LinkedIn
+# Log in using Google, GitHub, or LinkedIn (defaults to 'default' profile)
 apinow auth login <google|github|linkedin>
 
-# Verify current authentication status and user identity details
+# Log in under a specific profile alias with an optional custom API URL
+apinow auth login google --profile work --api-url https://api.apinow.app
+
+# Verify current authentication status and active profile details
 apinow auth status
 
-# Log out and erase stored authentication tokens
-apinow auth logout
+# Log out and remove credentials for the active profile (or a specified profile)
+apinow auth logout [--profile <name>]
 ```
 
-*Note: On your first login or checking status with no registered organization, an interactive step will automatically guide you through creating your first organization with live slug verification.*
+_Note: On your first login or checking status with no registered organization, an interactive step will automatically guide you through creating your first organization with live slug verification._
+
+#### Authentication Profiles (`auth profile`)
+
+Manage multiple authentication profiles to switch seamlessly between organizations or accounts.
+
+```bash
+# List all configured authentication profiles (active profile marked with *)
+apinow auth profile list
+
+# Switch to a different profile
+apinow auth profile use <profile_name>
+
+# Switch to a profile and verify that its authentication token is still valid
+apinow auth profile use <profile_name> --verify
+
+# Delete a configured profile
+apinow auth profile delete <profile_name>
+```
 
 #### Personal Access Tokens (`auth tokens`)
+
 Generate and manage Personal Access Tokens (PATs) for programmatic access.
 
 ```bash
@@ -78,14 +107,15 @@ apinow auth tokens list
 # Create a new personal access token
 apinow auth tokens create [--name <token_name>] [--expires-at <duration_or_timestamp>]
 
-Example:
-apinow auth tokens create --name "Test Token" --expires-at "30 days"
+# Example:
+apinow auth tokens create --name "CI Deploy Token" --expires-at "30 days"
 
 # Delete a personal access token by its ID
 apinow auth tokens delete <token_id>
 ```
 
 ### 3. Organizations (`orgs`)
+
 Manage organization contexts.
 
 ```bash
@@ -100,6 +130,7 @@ apinow orgs set-default <organization_id>
 ```
 
 ### 4. Files (`files`)
+
 Manage domain and API files in your organizations.
 
 ```bash
@@ -107,7 +138,7 @@ Manage domain and API files in your organizations.
 apinow files list --org <org_id> --parent <parent_id> --kind <domain|api>
 
 # Create file metadata and upload local media
-apinow files create --name "My Domain File" --kind "domain" --org <org_id> --parent <parent_id> --media ./path/to/schema.ts
+apinow files create --name "My Domain File" --kind "domain" --org <org_id> --parent <parent_id> --media ./path/to/schema.json
 
 # Create file metadata and pipe media contents from STDIN
 echo '{"schema": "content"}' | apinow files create --name "My Piped File" --kind "api" --org <org_id> --stdin
@@ -116,21 +147,155 @@ echo '{"schema": "content"}' | apinow files create --name "My Piped File" --kind
 apinow files read --id <file_id> --org <org_id> [--media]
 ```
 
-### 5. Data Catalog (`catalog`)
-Publish and browse published catalog items.
+### 5. Data Domains (`domain`)
+
+Manage Data Domain files, lifecycles, and catalog publications.
+
+#### List Data Domains (`domain list`)
+
+List all Data Domain files in an organization.
+
+```bash
+# List all domain files in an organization
+apinow domain list [--org <org_id>] [--parent <parent_id>]
+```
+
+#### Create Data Domain (`domain create`)
+
+Create a new Data Domain file record in your organization, with optional local schema or STDIN upload.
+
+```bash
+# Create a data domain metadata record
+apinow domain create --name "Billing Domain" [--org <org_id>]
+
+# Create a data domain and upload local schema media
+apinow domain create --name "Billing Domain" --media ./domain.json [--org <org_id>]
+
+# Create a data domain with schema piped from STDIN
+cat ./domain.json | apinow domain create --name "Piped Domain" --stdin [--org <org_id>]
+```
+
+#### Read Data Domain (`domain read`)
+
+Read Data Domain file metadata or schema media content.
+
+```bash
+# Read domain file metadata
+apinow domain read --file <file_id> [--org <org_id>]
+
+# Read domain schema media content (JSON)
+apinow domain read --file <file_id> --media [--org <org_id>]
+```
+
+#### Lifecycle Transitions (`domain transition`)
+
+Transition the state of a data domain (`draft`, `committed`, `published`).
 
 ```bash
-# Publish a local data domain file to the catalog
-apinow catalog publish --file <file_id> --name "Catalog Name" --description "Catalog Description" --scope public --catalog-version 1.0.0
+# Transition domain to committed state
+apinow domain transition committed --file <file_id> [--org <org_id>]
 
-# List all published data domains in the catalog
-apinow catalog list --scope <all|public|organization|private> [--key <domain_key>]
+# Transition published domain to draft with a new semantic version
+apinow domain transition draft --file <file_id> --ver 1.1.0 [--org <org_id>]
 ```
 
-### 6. Runtime (`runtime`)
+#### Mutating Data Domains (`domain mutate` / `domain apply`)
+
+Mutate an existing Data Domain schema by comparing a target local schema file or STDIN stream against the current server version, computing a JSON patch (RFC 6902), and sending the patch to the server using optimistic concurrency control.
+
+The target file ID is automatically extracted from the schema's `key` property.
+
+```bash
+# Mutate a data domain using a local schema file
+apinow domain mutate ./domain.json [--org <org_id>]
+
+# Mutate a data domain via STDIN (e.g. piped from an editor or generator)
+cat ./domain.json | apinow domain mutate --stdin [--org <org_id>]
+
+# Using the 'apply' alias
+apinow domain apply ./domain.json
+
+# Preview diff operations without applying changes
+apinow domain mutate ./domain.json --dry-run
+
+# Options:
+#   [file]                   Path to the local Data Domain schema JSON file
+#   --stdin                  Read domain schema content from STDIN
+#   --file <fid>             File ID of the data domain (optional, asserts match with schema key)
+#   --id <fid>               File ID alias
+#   --org <oid>              Organization ID (optional, defaults to configured default org)
+#   --dry-run                Compute diff and preview patch operations without applying them
+#   --no-validate            Skip local pre-flight domain schema validation
+#   -y, --yes                Automatically accept confirmation prompts for destructive changes
+```
+
+#### Publishing Domains (`domain publish`)
+
+Validates the domain schema, transitions its lifecycle to `committed`, patches the server-side media file, and publishes the domain and version to the Data Catalog.
+
+```bash
+# Publish a data domain file to the Data Catalog
+apinow domain publish --file <file_id> --ver 1.0.0 --scope public --name "Billing Domain" --description "Domain for Billing Services"
+
+# Options:
+#   --file <fid>             File ID of the data domain (prompts interactively if omitted)
+#   --org <oid>              Organization ID (optional, defaults to configured default org)
+#   --ver <ver>              Semantic version to publish (e.g. 1.0.0)
+#   --scope <scope>          Publish scope: public, organization, private (default: "public")
+#   --name <name>            Name for the catalog entry (defaults to domain name)
+#   --description <desc>     Description of the catalog entry (defaults to domain description)
+#   --lifecycle <lifecycle>  Version lifecycle status: dev, beta, stable (default: "stable")
+#   --changelog <changelog>  Changelog description for this version
+```
+
+### 6. Schema Validation (`validate`)
+
+Validate local or remote Data Domain and API Model schemas against syntax, modeling rules, and naming conventions.
+
+```bash
+# Validate a local Data Domain or API Model schema file
+apinow validate ./domain.json
+
+# Validate an API Model against a local Data Domain dependency
+apinow validate ./api.json --domain ./domain.json
+
+# Validate a schema streamed via STDIN
+cat domain.json | apinow validate --stdin
+
+# Validate a remote file stored in an organization
+apinow validate --org <org_id> --fid <file_id>
+```
+
+### 7. Data Catalog (`catalog`)
+
+Publish, inspect, and manage published catalog items.
+
+```bash
+# List all published items in the catalog (or versions of a specific item)
+apinow catalog list [--scope <all|public|organization|private>] [--key <catalog_key>]
+
+# Show details of a catalog entry or specific version
+apinow catalog show <catalog_key> [--ver <version>]
+
+# Check publication status for a data domain file
+apinow catalog status <file_id> [--org <org_id>]
+
+# List APIs depending on a catalog item or specific version
+apinow catalog dependent-apis <catalog_key> [--ver <version>]
+
+# Deprecate a catalog entry or specific version
+apinow catalog deprecate <catalog_key> --reason "Superseded by v2" [--ver <version>]
+
+# Unpublish a catalog entry or specific version
+apinow catalog unpublish <catalog_key> [--ver <version>]
+```
+
+### 8. Runtime (`runtime`)
+
 Administrative operations for the API runtime. This command allows API Now! platform managers and administrators to modify runtime users directly.
 
 #### Bypass Authorization Restrictions
+
 By default, the API's semantic pipeline does not allow granting permissions to a user that exceed the permissions of the authenticated caller. Consequently, an API user cannot be granted permissions higher than the lowest permission in the chain.
 
 The `runtime users update` command bypasses this restriction by writing updates directly to the runtime database, allowing administrators to designate users with higher permissions or update arbitrary properties.
@@ -145,26 +310,28 @@ apinow runtime users update --api api-123 --user-id user-123 --property role=adm
 
 ---
 
-
 ## Development
 
 ### Local Setup & Building
 
 > [!NOTE]
 > This project depends on private workspace packages (such as `@api-now/core`) during development and local testing. Before running `npm install`, ensure you have configured a local `.npmrc` file at the root of the workspace with access to the private registry.
-> 
+>
 > Example `.npmrc`:
+>
 > ```ini
 > @api-now:registry=https://registry.npmjs.org/
 > //registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN
 > ```
 
 1. Clone the repository, set up your `.npmrc`, and install dependencies:
+
    ```bash
    npm install
    ```
 
 2. Build the package:
+
    ```bash
    npm run build
    ```
@@ -178,19 +345,24 @@ apinow runtime users update --api api-123 --user-id user-123 --property role=adm
    node dist/index.js [command]
    ```
 
-### Formatting and Linting
-To format the source code with Prettier:
+### Formatting, Linting, and Type Checking
+
 ```bash
+# Format source code with Prettier
 npm run format
-```
 
-To run the ESLint static code analysis checks:
-```bash
+# Run ESLint static analysis
 npm run lint
+
+# Run TypeScript compiler type checking
+npm run typecheck
+
+# Check unused exports and dependencies
+npm run knip
 ```
 
-### Type Checking
-To run the TypeScript compiler in dry-run mode:
+### Running Tests
+
 ```bash
-npm run typecheck
+npm run test
 ```