@api-now/cli 1.8.0 → 1.10.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,12 +32,15 @@ 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.
+
+- `--api-url <url>`: Override the target API Server URL (Default: `http://localhost:8080`).
 - `--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:
+
 - **Linux**: `~/.config/apinow-cli/config.json` (or respects `$XDG_CONFIG_HOME`)
 - **macOS**: `~/Library/Preferences/apinow-cli/config.json`
 - **Windows**: `%APPDATA%\apinow-cli\config.json`
@@ -50,9 +55,16 @@ apinow config get <key>
 
 # Set a configuration property
 apinow config set <key> <value>
+
+# List all current configuration settings
+apinow config list
+
+# Reset configuration to default values
+apinow config reset
 ```
 
 ### 2. Authentication (`auth`)
+
 Securely log in to the API platform using OAuth2.
 
 ```bash
@@ -66,9 +78,10 @@ apinow auth status
 apinow auth logout
 ```
 
-*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._
 
 #### Personal Access Tokens (`auth tokens`)
+
 Generate and manage Personal Access Tokens (PATs) for programmatic access.
 
 ```bash
@@ -78,14 +91,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 +114,7 @@ apinow orgs set-default <organization_id>
 ```
 
 ### 4. Files (`files`)
+
 Manage domain and API files in your organizations.
 
 ```bash
@@ -107,7 +122,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 +131,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
+# Transition domain to committed state
+apinow domain transition committed --file <file_id> [--org <org_id>]
+
+# Transition published domain to draft with a new semantic version
+apinow domain transition draft --file <file_id> --ver 1.1.0 [--org <org_id>]
+```
+
+#### 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
-# 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
+# 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>]
 
-# List all published data domains in the catalog
-apinow catalog list --scope <all|public|organization|private> [--key <domain_key>]
+# Unpublish a catalog entry or specific version
+apinow catalog unpublish <catalog_key> [--ver <version>]
 ```
 
-### 6. Runtime (`runtime`)
+### 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 +294,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 +329,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
 ```