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

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

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

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

# Get a configuration property (e.g. apiUrl, defaultOrg)
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.

# Log in using Google, GitHub, or LinkedIn
apinow auth login <google|github|linkedin>

# Verify current authentication status and user identity details
apinow auth status

# Log out and erase stored authentication tokens
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.

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.

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

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

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

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

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.

# 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

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