lofty-cli

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

Install

npx api2cli install <user>/lofty-cli

This clones the repo, builds the CLI, links it to your PATH, and installs the AgentSkill to your coding agents.

Install AgentSkill only

npx skills add <user>/lofty-cli

The AgentSkill is located at skills/lofty-cli/SKILL.md in the repository. It describes all available resources, commands, and authentication options for use with AI coding agents.

Authentication

lofty-cli supports three authentication modes:

Mode 1: OAuth2 Client Credentials (Recommended)

This mode uses vendor credentials + user's customer key to automatically obtain and cache an access_token.

How to get these credentials: Log in to the Lofty CRM, go to Settings > Integrations > API to find your Client ID, Client Secret, and Customer Key.

Step 1: Configure vendor credentials (environment variables)

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

These are issued to your vendor/integration by Lofty.

Step 2: Configure user's customer key

Option A — Environment variable:

export LOFTY_CUSTOMER_KEY="eyJhbGciOiJIUzI1NiJ9..."

Option B — Save to local file:

lofty-cli auth set "eyJhbGciOiJIUzI1NiJ9..."

The customer key is stored at ~/.config/tokens/lofty-cli.txt with chmod 600.

Step 3: Verify

# Check authentication status
lofty-cli auth status

# Manually obtain an access_token
lofty-cli auth login

# Test with a real API call
lofty-cli auth test

How it works

1. CLI calls POST {BASE_URL}/oauth/token with client_id, client_secret, customer_key, grant_type=client_credentials, scope=openapi
2. The returned access_token is cached locally at ~/.config/tokens/lofty-oauth-cache.json
3. Cached token is reused until it expires (auto-refreshes 5 minutes before expiry)
4. All API requests use Authorization: Bearer <access_token>

Mode 2: OAuth PKCE — Browser Authorization (Interactive)

This mode uses OAuth 2.0 Authorization Code Flow with PKCE (S256). The CLI opens a browser window for the user to log in and authorize. No client_secret is needed — the CLI is a public client secured by PKCE.

Step 1: Authorize via browser

lofty-cli auth login-browser

What happens:

1. If a browser can be opened, it opens automatically with the authorization page
2. If not (e.g., SSH session), a URL is printed for manual copy-paste
3. You log in and click "Authorize" in the browser
4. The CLI receives the authorization code (via polling or manual paste)
5. The code is exchanged for access_token + refresh_token using PKCE

Step 2: Verify

lofty-cli auth status    # Shows PKCE token status
lofty-cli auth test      # Test with a real API call

How it works

1. CLI generates a random code_verifier and computes code_challenge = BASE64URL(SHA256(code_verifier))
2. Browser opens {AUTH_BASE}/page/vendor-auth.html?clientId=...&code_challenge=...&code_challenge_method=S256
3. User logs in and authorizes
4. CLI gets the authorization code (via server polling or user paste)
5. CLI exchanges code + code_verifier at POST {AUTH_BASE}/api/user-web/oauth/token
6. The returned tokens are stored at ~/.config/tokens/lofty-pkce-token.json (chmod 600)
7. Cached token is reused until it expires
8. All API requests use Authorization: Bearer <access_token>

Mode 3: Direct API Key (Legacy)

If vendor credentials (LOFTY_CLIENT_ID / LOFTY_CLIENT_SECRET) are not configured, the CLI falls back to using the customer key directly as the Authorization header value.

# Set customer key
lofty-cli auth set "your-api-key"

# Or via environment variable
export LOFTY_CUSTOMER_KEY="your-api-key"

Environment Variables

Usage

# View all available resources
lofty-cli --help

# Examples
lofty-cli leads list
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 list

Resources

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

Auth Commands

Global Flags

All commands support: