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.

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 Catalog Publishing: Publish schemas and datasets to the global/private catalog with automatic semantic versioning support.
• 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). 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.

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>

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 "Test 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.ts

# 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 Catalog (catalog)

Publish and browse published catalog items.

# 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 data domains in the catalog
apinow catalog list --scope <all|public|organization|private> [--key <domain_key>]

6. 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 and Linting

To format the source code with Prettier:

npm run format

To run the ESLint static code analysis checks:

npm run lint

Type Checking

To run the TypeScript compiler in dry-run mode:

npm run typecheck