API NOW! CLI

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.

Features

• OAuth2 Loopback Authentication: Authenticate using your Google, GitHub, or LinkedIn accounts.
• 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: 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 & Code Generation: Search, list, create, and read API Model files, generate OpenAPI Specifications (OAS 3.1), and generate type-safe TypeScript client SDKs.
• 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.
• Deployment Management: List deployments filtered by API ID, inspect environments (production, staging, development), deployment statuses, model versions, and base URIs with robust permission and error handling.
• Developer Formatting Options: Toggle outputs between human-friendly ASCII tables and machine-readable JSON.

Installation

Install the CLI globally from npm:

npm install -g @api-now/cli

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):

• --format <text|json>: Define the output layout (Default: text).
• --debug / -v, --verbose: Enable debug/verbose logging.

1. Configuration (config)

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 (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.

# Get a configuration property (e.g. apiUrl, defaultOrg, activeProfile)
apinow config get <key>

# Reset configuration to default values
apinow config reset

2. Authentication (auth)

Securely log in to the API Now platform using OAuth2.

# Log in using Google, GitHub, or LinkedIn (defaults to 'default' profile)
apinow auth login <google|github|linkedin>

# 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 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.

# 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.

# List all personal access tokens
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 "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.

# List all organizations you belong to
apinow orgs list

# Get the default configured organization
apinow orgs get-default

# Set default organization to avoid passing --org CLI parameters
apinow orgs set-default <organization_id>

4. Files (files)

Manage domain and API files in your organizations.

# List files with optional filters
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.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

# Read file metadata (default) or media content (--media)
apinow files read --id <file_id> --org <org_id> [--media]

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 (flat listing across all folders with immediate parent folder resolution).

# 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.

# 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.

# Create a data domain metadata record
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>]

# 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.

# 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).

# 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.

# 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.

# 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. 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).

# 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.

# 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.

# 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.

# 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>]

Generate OpenAPI Specification (api oas)

Generate an OpenAPI Specification (OAS 3.1) from an API model (live cloud model, local schema file, or STDIN).

# Generate OAS from a remote API model file (automatically resolves Data Domain from Data Catalog)
apinow api oas --file <file_id> [--org <org_id>]

# Generate OAS with custom server URL(s)
apinow api oas <file_id> --server https://api.example.com/v1

# Generate OAS from local files
apinow api oas ./api.json --domain ./domain.json

# Generate OAS from schema piped via STDIN
cat ./api.json | apinow api oas --stdin --domain ./domain.json

# Save OAS output directly to a file
apinow api oas <file_id> -o ./openapi.json

Generate TypeScript Client SDK (api sdk)

Generate a type-safe TypeScript client SDK from an API model (live cloud model, local schema file, or STDIN). Supports generating raw source files directly into a project or a complete standalone npm package.

# Generate SDK files into the current working directory from a remote API model
apinow api sdk --file <file_id> [--org <org_id>]

# Generate SDK files into a designated output directory
apinow api sdk <file_id> -o ./src/sdk

# Generate SDK from local API model and Data Domain schema files
apinow api sdk ./api.json --domain ./domain.json -o ./sdk

# Generate SDK from schema piped via STDIN
cat ./api.json | apinow api sdk --stdin --domain ./domain.json -o ./sdk

# Generate a standalone npm package with package.json and tsconfig.json
apinow api sdk <file_id> --standalone --package-name @my-org/my-api-sdk -o ./packages/my-api-sdk

# Bake a base URL directly into the generated SDK client
apinow api sdk <file_id> --base-url https://api.example.com/v1

# Read the base URL automatically from an active deployment
apinow api sdk <file_id> --deployment <deployment_id>

[!TIP] Base URL Resolution & Interactive Mode: When generating an SDK for a remote API model without specifying --base-url or --deployment, the CLI in interactive TTY mode will prompt you to select an active deployment, enter a custom base URL, or skip baking the base URL so that consumers configure it at client initialization.

7. Schema Validation (validate)

Validate local or remote Data Domain and API Model schemas against syntax, modeling rules, and naming conventions.

# 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>

8. Data Catalog (catalog)

Publish, inspect, and manage published catalog items.

# 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>]

9. 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.

# Update properties of a user in the runtime database (bypasses semantic pipeline limits)
apinow runtime users update --api <api_file_id_or_slug> --user-id <user_id> --property <name=value...> [--org <org_id>] [--env <environment>]

# Example: Grant admin role and set a premium tier for user-123 in production
apinow runtime users update --api api-123 --user-id user-123 --property role=admin tier=premium --org org-123

10. Deployments (deployment)

Manage API deployments in your organizations.

List Deployments (deployment list)

List all deployments for a specific API model file. Filter deployments by providing the API ID as a positional argument or with the --api option (alias: --file, --id).

[!NOTE] Viewing deployments requires appropriate organization permissions. If your user account or token does not have permission to view deployments, the command returns an error (CLI_ERR_FORBIDDEN).

# List deployments for an API by ID (positional argument)
apinow deployment list <api_file_id> [--org <org_id>]

# List deployments using the --api flag
apinow deployment list --api <api_file_id> [--org <org_id>]

# List deployments using the --file flag alias
apinow deployment list --file <api_file_id> [--org <org_id>]

# Limit the number of deployment records returned
apinow deployment list <api_file_id> --limit 10

# Output deployment details in machine-readable JSON format
apinow deployment list <api_file_id> --format json

Read Deployment Details (deployment read / deployment get)

Read the detailed status and configuration of a specific deployment (including environments, base URI, portal URI, versions, and CORS settings).

# Read deployment details by ID (positional argument)
apinow deployment read <deployment_id> [--org <org_id>]

# Using the 'get' alias
apinow deployment get <deployment_id> [--org <org_id>]

# Read deployment using the --id flag
apinow deployment read --id <deployment_id> [--org <org_id>]

# Read deployment using the --deployment flag alias
apinow deployment get --deployment <deployment_id> [--org <org_id>]

# Output deployment details in machine-readable JSON format
apinow deployment read <deployment_id> --format json

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:

@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:

   npm install

2. Build the package:

   npm run build

3. Run the CLI locally:

   # Run directly via tsx (Development)
   npm run dev -- [command]
   
   # Or execute the compiled build
   node dist/index.js [command]

Formatting, Linting, and Type Checking

# Format source code with Prettier
npm run format

# Run ESLint static analysis
npm run lint

# Run TypeScript compiler type checking
npm run typecheck

# Check unused exports and dependencies
npm run knip

Running Tests

npm run test