lofty-cli

CLI for the Lofty CRM API. Made with api2cli.dev.

Install

npm i @loftyai/lofty-cli

Authentication

/ lofty-cli supports multiple authentication methods with automatic priority fallthrough. Choose the one that fits your use case.

Method 1: Token URL (CI/CD & Automation — Highest Priority)

For automated environments where you exchange a session ID for tokens via a custom endpoint. Set two env vars; tokens are fetched and cached automatically.

export LOFTY_TOKEN_URL="https://your-auth-server.com/api/token"
export LOFTY_SESSION_ID="your_session_id"

To explicitly fetch and verify:

lofty-cli auth login-session
# Or with inline flags (overrides env vars):
lofty-cli auth login-session --tokenurl https://... --sessionid your_session_id

Tokens are cached in ~/.config/tokens/lofty-session-cache.json and refreshed automatically when expired.

Method 2: Browser Authorization (Recommended for humans)

The simplest way to authenticate — open a browser, log in, and you're done.

lofty-cli auth login-browser

The browser opens the Lofty login page. After you log in and authorize, the CLI saves the token locally and auto-refreshes it when it expires.

Method 3: OAuth2 Client Credentials

For server-to-server integrations. Requires three credentials.

Step 1: Configure vendor credentials

export LOFTY_CLIENT_ID="your_client_id"
export LOFTY_CLIENT_SECRET="your_client_secret"

Register a developer account at Lofty Vendor Portal to obtain these.

Step 2: Configure customer key

Option A — Environment variable:

export LOFTY_CUSTOMER_KEY="eyJhbGciOiJIUzI1NiJ9..."

Option B — Save to local file:

lofty-cli auth set "eyJhbGciOiJIUzI1NiJ9..."

Log in to Lofty CRM → Settings > Integrations > API to find your Customer Key.

Method 4: Direct Access Token

If you already have an access_token (e.g., from CI/CD or another system):

export LOFTY_ACCESS_TOKEN="your_access_token"
export LOFTY_REFRESH_TOKEN="your_refresh_token"

Verify Authentication

lofty-cli auth status   # Show authentication status (all levels)
lofty-cli auth test     # Verify with a real API call

Environment Variables

Usage

# View all available resources
lofty-cli --help

# Examples
lofty-cli leads list
lofty-cli leads list --key "John Smith" --json  # fuzzy search by name, phone, or email
lofty-cli leads list --return-fields "leadId,firstName,stage" --json  # reduce response to specific fields
lofty-cli leads get --id "lead_id"
lofty-cli leads create --body '{"first_name":"John","last_name":"Doe"}'

lofty-cli transaction list
lofty-cli communication list
lofty-cli tasks-appointments-v2 list --lead-id "lead_id"
lofty-cli calendar-v2 list --lead-id "lead_id"

Note: The tasks resource is deprecated. Use tasks-appointments-v2 for task/appointment management and calendar-v2 for calendar/meeting management instead.

Resources

Run lofty-cli <resource> --help for detailed commands and options.

Auth Commands

Update Notifications

lofty-cli checks for new versions in the background (at most once every 24 hours). If a newer version is available, a one-line upgrade hint is shown:

Update available: 0.3.1 → 0.4.0
Run: npm install -g @loftyai/lofty-cli

Global Flags

All commands support:

Boolean Flags

Flags shown as --flag <bool> in --help require an explicit true or false string value:

lofty-cli leads list --contacted true    # filter to contacted leads
lofty-cli leads list --contacted false   # filter to non-contacted leads

Omitting the flag uses the API's default behavior. Boolean flags do not use --no-flag syntax.

Return Fields (leads list)

Use --return-fields to reduce the API response to only the fields you need. This sends the returnFields parameter to the API and filters the response client-side.

lofty-cli leads list --return-fields "leadId,firstName,stage" --json   # 5 keys instead of 61
lofty-cli leads list --return-fields "leadId,firstName,address" --json # address expands to 4 fields

Available field names (mapped to API paths automatically):

Unmapped field names are passed through as data.lead.{name} automatically.

Other Filter Flags (leads list)

leads list supports 37 advanced filter flags that map to LeadFilter fields. They are assembled into the otherFilters JSON query parameter at runtime.

# Buyer leads with a phone number, never contacted
lofty-cli leads list --lead-types "2" --has-phone-state 1 --never-touched true --json

# Leads registered in 2024 with price range 500K–1M
lofty-cli leads list --reg-start-time "2024-01-01" --reg-end-time "2024-12-31" \
  --min-price 500000 --max-price 1000000 --json

# Include deleted seller leads
lofty-cli leads list --lead-types "1" --with-trash true --json

Run lofty-cli leads list --help for full descriptions and enum values.