SmallForce CLI

Command-line access to SmallForce OS. Use it to inspect your organization, deploy generated apps, manage integrations and triggers, run integration tools, generate AI media, operate voice calls, and manage social channels.

Install

npm install -g smallforce
smallforce --help

You can also run it without installing globally:

npx smallforce --help

Quick Start

export SMALLFORCE_API_KEY=sf_sk_live_xxx

smallforce org details
smallforce profiles list
smallforce integrations list
smallforce social platforms
smallforce calls credits

Run smallforce <command> --help before a workflow. The CLI help includes the current command order, ID discovery steps, and payload examples.

Authentication

Set an API key in the environment, or pass it with --api-key.

export SMALLFORCE_API_KEY=sf_sk_live_xxx
smallforce org details

smallforce org details --api-key sf_sk_live_xxx

Environment variables:

| Variable | Description | Default | | --- | --- | --- | | SMALLFORCE_API_KEY | SmallForce API key used as a Bearer token | Required | | SMALLFORCE_BASE_URL | Backend URL override for local or staging tests | https://backend.smallforcehq.com | | SMALLFORCE_APP_TEMPLATE_URL | Template URL used by smallforce app init | SmallForce website template |

Command Map

| Command | Use it for | | --- | --- | | smallforce org | Organization details and API key smoke tests | | smallforce app | Current-project generated app init, deploy, status, DB, and storage using smallforce.json | | smallforce apps | Direct generated app API commands when you already have app and deployment IDs | | smallforce profiles | SmallForce OS employee profile discovery for routed work | | smallforce integrations | OAuth lifecycle and connection status for Gmail, Slack, HubSpot, Google Calendar, and other integrations | | smallforce tools | Search, inspect, and execute integration tools | | smallforce triggers | Route integration events to SmallForce OS employee profiles | | smallforce ai | Backend-managed image generation, image editing, video generation, and video job lookup | | smallforce calls | Voice assistants, phone numbers, knowledge, call tags, call history, and voice credits | | smallforce social | Social profiles, accounts, posts, assets, comments, inbox, reviews, analytics, ads, Reddit, and Google Business | | smallforce inbox | Legacy organization inbox conversation commands | | smallforce reviews | Legacy Google Business review commands |

Generated Apps

Use smallforce app when you are creating or deploying a local generated app project. It writes and updates smallforce.json, so later commands can infer the app and deployment IDs.

smallforce app init --name "Acme CRM" --slug acme-crm --db
cd acme-crm
smallforce app deploy
smallforce app status

Common app commands:

| Command | Description | | --- | --- | | smallforce app init | Create a local project from the template, create the backend app record, and write smallforce.json | | smallforce app update | Update current app metadata, currently the slug | | smallforce app db enable | Enable backend-mediated database access for the current app | | smallforce app storage upload | Upload a local file or URL into current app storage | | smallforce app storage list | List current app storage objects | | smallforce app storage get | Create a temporary download URL | | smallforce app storage delete | Delete an app storage object | | smallforce app deploy | Build, zip, upload, and queue backend-managed deployment | | smallforce app status | Read app and deployment status, then refresh smallforce.json |

Use smallforce apps for lower-level API-style work when you already have IDs:

smallforce apps create --name "Acme Site" --slug acme-site --type static
smallforce apps deploy <app-id> --artifact ./dist.zip --capabilities '{"db":true}'
smallforce apps deployments get <app-id> <deployment-id>
smallforce apps db ensure <app-id> <deployment-id>
smallforce apps db query <app-id> <deployment-id> --sql "SELECT 1" --params '[]'
smallforce apps storage upload <app-id> <deployment-id> ./logo.png --path assets/logo.png

Integrations, Tools, and Triggers

Use integrations to connect external systems, tools to execute actions, and triggers to route incoming events to SmallForce OS employee profiles.

smallforce integrations list
smallforce integrations status gmail
smallforce integrations connect gmail

smallforce tools search "send an email" --integration gmail
smallforce tools get GMAIL_SEND_EMAIL
smallforce tools execute GMAIL_SEND_EMAIL --input '{"to":"[email protected]","subject":"Hello","body":"Draft text"}'

smallforce profiles list
smallforce triggers list --integration gmail
smallforce triggers get GMAIL_NEW_GMAIL_MESSAGE
smallforce triggers enable --integration gmail
smallforce triggers create --integration gmail --trigger GMAIL_NEW_GMAIL_MESSAGE --profile emma --message "Review this email and decide if it needs a reply." --include-payload

For tools execute, inspect the schema with tools get first. Pass arguments with --input '<json>', --input-file ./args.json, or --input-file - for stdin.

AI Media

SmallForce AI commands run through the SmallForce backend. The backend owns provider credentials, validates options, queues video jobs, and handles billing.

Image commands:

smallforce ai image models
smallforce ai image model openai/gpt-image-2
smallforce ai image generate --prompt "Clean hero image for a plumbing website" --image-size square_hd --quality medium --output ./hero.png
smallforce ai image edit --input ./photo.png --prompt "Make this room look like a premium office" --output ./office.png --overwrite

Video commands:

smallforce ai video models
smallforce ai video model seedance-2-fast-text
smallforce ai video generate --model seedance-2-fast-text --prompt "Short Meta ad for an HVAC business" --duration 5 --resolution 720p --aspect-ratio 16:9 --output ./ad.mp4
smallforce ai video animate --model seedance-2-fast-image --input ./hero.png --prompt "Slow cinematic camera push in" --duration 5 --resolution 720p --aspect-ratio 16:9 --output ./hero.mp4
smallforce ai video job <job-id> --output ./ad.mp4

Supported image models are openai/gpt-image-2 and openai/gpt-image-2/edit. Use smallforce ai image model <model-id> and smallforce ai video model <model-id> for current option schemas.

Voice Calls

Use smallforce calls for the current SmallForce voice system. These commands map to /api/sdk/voice.

smallforce calls credits
smallforce calls assistants create --name "Front Desk" --status active --system-prompt @prompt.txt
smallforce calls phone-numbers capacity
smallforce calls phone-numbers search --country-code US --area-code 415 --limit 5
smallforce calls phone-numbers buy --phone-number +14155550123 --assistant-id <assistant-id>
smallforce calls knowledge train-url --assistant-id <assistant-id> --url https://example.com/faq
smallforce calls tags create --name "Escalated" --color "#dc2626" --description "Needs owner attention"
smallforce calls tags assign <voice-session-id> --tag-ids <tag-id>,<tag-id>
smallforce calls list --assistant-id <assistant-id> --limit 20
smallforce calls get <voice-session-id>

Voice command groups:

| Command | Description | | --- | --- | | calls credits | Show voice credit balance | | calls assistants | List, create, get, update, and delete voice assistants | | calls phone-numbers | Check capacity, search, buy, attach, detach, sync webhooks, and delete numbers | | calls knowledge | Train from text, URL, or backend document storage keys | | calls tags | Manage org-wide call tags and assign tags to sessions | | calls list | List voice sessions with filters such as assistant, status, channel, and tag IDs | | calls get | Read one call with events, transcript, and recording metadata |

Social Media

Use smallforce social platforms first. It reports the posting, ads, analytics, review, and platform-option support currently available to your organization.

smallforce social platforms
smallforce social profiles list
smallforce social profiles create --name "Acme Main" --description "Primary brand profile"
smallforce social connect --profile-id <profile-id> --platform instagram
smallforce social accounts list --kind posting
smallforce social accounts disconnect --account-id <account-id>

Posting workflow:

smallforce social assets upload ./photo.jpg
smallforce social posts create --content "Hello from SmallForce" --account-id <account-id> --mode draft
smallforce social posts create --content "We are open today" --account-id <account-id> --mode now
smallforce social posts create --content "Scheduled post" --account-id <account-id> --mode schedule --scheduled-for 2026-07-01T14:00:00Z
smallforce social posts get <post-id>
smallforce social posts sync <post-id>

For one posting target, pass --account-id <id> and optional --platform-options '<json>'. For multiple targets, pass --publications '[{"accountId":"...","platformOptions":{...}}]'.

Social command groups:

| Command | Description | | --- | --- | | social platforms | List supported platforms and option schemas | | social profiles | Group connected social accounts and posts | | social accounts | List and disconnect connected posting or ads accounts | | social connect | Create an OAuth connect URL for posting platforms | | social assets | Upload media and create temporary public URLs | | social posts | Create, update, list, get, and sync social posts | | social inbox | List and reply to supported social inbox conversations | | social comments | Fetch, reply, moderate, hide, like, and private-reply to supported comments | | social reddit | Discover subreddits, flairs, and validate subreddit names | | social google-business | Manage locations, selected location, details, and media | | social reviews | Fetch, reply to, and delete replies for social reviews | | social analytics | Read post, daily, follower, Instagram, Facebook, and Google Business metrics | | social ads | Connect ad surfaces, list ad accounts, create ads, boost posts, and manage campaigns/ad sets |

Ads workflow:

smallforce social ads connect --profile-id <profile-id> --platform meta_ads
smallforce social accounts list --kind ads
smallforce social ads accounts --social-account-id <social-account-id>
smallforce social ads campaigns list --social-account-id <social-account-id>
smallforce social ads campaigns tree --social-account-id <social-account-id>
smallforce social ads create --social-account-id <social-account-id> --ad-account-id <ad-account-id> --idempotency-key <request-id> --payload '{"name":"Local service ad","imageAssetId":"<asset-id>"}'

For ad creative, upload media with smallforce social assets upload first, then use helper keys in --payload, such as imageAssetId, imageAssetPath, videoAssetId, videoAssetPath, thumbnailAssetId, landscapeAssetId, or squareAssetId.

Inbox and Reviews

smallforce inbox conversations --limit 25
smallforce inbox conversation-messages <conversation-id>
smallforce inbox send <conversation-id> --message "Thanks for reaching out."

smallforce reviews list --needs-response
smallforce reviews reply <review-id> --message "Thank you for the feedback."

Output and Errors

Most read commands print formatted JSON from the SmallForce backend. Failed backend requests print the backend error message and hint when one is available.

For local backend testing:

SMALLFORCE_BASE_URL=http://localhost:3005 smallforce org details

Links

• SmallForce: https://smallforcehq.com
• Docs: https://smallforcehq.com/docs
• Download: https://smallforcehq.com/download/

License

MIT