@api-now/cli 1.10.0 → 1.12.0

package/README.md

@@ -10,7 +10,8 @@ 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 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.
+- **Data Domain Management & Publishing**: Search, list, create, mutate via declarative JSON patch diffing, transition lifecycles (`draft`, `committed`, `published`), bump versions, run pre-publish validation, and publish domains directly to the Data Catalog.
+- **API Model Management**: Search, list, create, and read API Model files and schemas with immediate parent folder resolution.
 - **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.
@@ -33,53 +34,69 @@ Once installed, the CLI is available as the `apinow` command.
 
 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`).
 - `--format <text|json>`: Define the output layout (Default: `text`).
 - `--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>
-
-# 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.
+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._
 
+#### 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.
@@ -137,20 +154,32 @@ Manage Data Domain files, lifecycles, and catalog publications.
 
 #### List Data Domains (`domain list`)
 
-List all Data Domain files in an organization.
+List all Data Domain files in an organization (flat listing across all folders with immediate parent folder resolution).
 
 ```bash
 # List all domain files in an organization
 apinow domain list [--org <org_id>] [--parent <parent_id>]
 ```
 
+#### Search Data Domains (`domain search`)
+
+Search for Data Domain files by name or keyword across the organization.
+
+```bash
+# Search for domain files matching a query keyword
+apinow domain search "Billing" [--org <org_id>]
+
+# Search with explicit query keywords and folder/result limits
+apinow domain search --query Billing Payments --parent <parent_id> --limit 10
+```
+
 #### 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>]
+apinow domain create --name "Billing Domain" [--org <org_id>] [--parent <parent_id>]
 
 # Create a data domain and upload local schema media
 apinow domain create --name "Billing Domain" --media ./domain.json [--org <org_id>]
@@ -232,7 +261,59 @@ apinow domain publish --file <file_id> --ver 1.0.0 --scope public --name "Billin
 #   --changelog <changelog>  Changelog description for this version
 ```
 
-### 6. Schema Validation (`validate`)
+### 6. API Models (`api`)
+
+Manage API model files and schema definitions.
+
+#### List API Models (`api list`)
+
+List all API model files in an organization (flat listing across all folders with immediate parent folder resolution).
+
+```bash
+# List all API model files in an organization
+apinow api list [--org <org_id>] [--parent <parent_id>]
+```
+
+#### Search API Models (`api search`)
+
+Search for API model files by name or keyword across the organization.
+
+```bash
+# Search for API model files matching a query keyword
+apinow api search "Payments" [--org <org_id>]
+
+# Search with explicit query keywords and folder/result limits
+apinow api search --query Payments Billing --parent <parent_id> --limit 10
+```
+
+#### Create API Model (`api create`)
+
+Create a new API model file record in your organization, with optional local schema or STDIN upload.
+
+```bash
+# Create an API model metadata record
+apinow api create --name "Payments API" [--org <org_id>] [--parent <parent_id>]
+
+# Create an API model and upload local schema media (validates Core#ApiModel schema)
+apinow api create --name "Payments API" --media ./api.json [--org <org_id>]
+
+# Create an API model with schema piped from STDIN
+cat ./api.json | apinow api create --name "Piped API" --stdin [--org <org_id>]
+```
+
+#### Read API Model (`api read`)
+
+Read API model file metadata or schema media content.
+
+```bash
+# Read API model file metadata
+apinow api read --file <file_id> [--org <org_id>]
+
+# Read API model schema media content (JSON)
+apinow api read --file <file_id> --media [--org <org_id>]
+```
+
+### 7. Schema Validation (`validate`)
 
 Validate local or remote Data Domain and API Model schemas against syntax, modeling rules, and naming conventions.
 
@@ -250,7 +331,7 @@ cat domain.json | apinow validate --stdin
 apinow validate --org <org_id> --fid <file_id>
 ```
 
-### 7. Data Catalog (`catalog`)
+### 8. Data Catalog (`catalog`)
 
 Publish, inspect, and manage published catalog items.
 
@@ -274,7 +355,7 @@ apinow catalog deprecate <catalog_key> --reason "Superseded by v2" [--ver <versi
 apinow catalog unpublish <catalog_key> [--ver <version>]
 ```
 
-### 8. Runtime (`runtime`)
+### 9. Runtime (`runtime`)
 
 Administrative operations for the API runtime. This command allows API Now! platform managers and administrators to modify runtime users directly.