Common Ninja CLI
commonninja is a command-line interface for creating and managing Common Ninja widgets. Every command prints structured JSON to stdout (errors as JSON to stderr, exit code 1), so it's ideal for AI agents, scripts, and automation pipelines that need to parse, plan, and execute without an SDK or verbose REST payloads.
It's the local counterpart to the hosted MCP server and talks to the same Platform API.
Install
Install globally from npm:
npm install -g @commonninja/cli
commonninja help
…or run it without installing:
npx @commonninja/cli help
Run from source
git clone https://github.com/CommonNinja/commonninja-mcp-server.git
cd commonninja-mcp-server
npm install
npm run build
node build/cli.js help
Authenticate
Set your Account API token (Common Ninja dashboard → Account → API key):
export COMMONNINJA_ACCOUNT_ACCESS_TOKEN="your_api_token"
Or pass it per-command with --token.
Usage
commonninja <command> [args] [--flags]
All output is JSON. Flags use --key value. The --data flag accepts inline JSON or @path/to/file.json.
Widgets
# List available widget types
commonninja widget-types
# Get the JSON schema for a type (follow it when creating/updating)
commonninja widget-schema reviews
# List widgets in the account
commonninja widgets:list --limit 20 --page 1 --search faq --type faq --project <projectId>
# Get a single widget (type + data)
commonninja widget:get <widgetId>
# Create a widget (data inline or from a file)
commonninja widget:create --type faq --name "My FAQ" --data '{"questions":[]}'
commonninja widget:create --type faq --data @faq.json --project <projectId>
# Update a widget's data
commonninja widget:update <widgetId> --data @faq.json
# Delete a widget
commonninja widget:delete <widgetId>
# Get embed code / editor URL
commonninja widget:embed <widgetId>
commonninja widget:editor <widgetId>
Projects
commonninja projects:list --limit 20 --page 1
commonninja project:get <projectId>
CRM (read-only)
commonninja contacts:list <projectId> --limit 20 --page 1
commonninja contact:get <projectId> <contactId>
commonninja submissions:list <projectId> --widget <widgetId>
commonninja submission:get <projectId> <submissionId>
Analytics
commonninja analytics <widgetId> --from 2026-01-01 --to 2026-01-31 --breakdown day --events view,click
Command reference
| Command | Description |
|---|---|
widget-types | List available widget types |
widget-schema <type> | Get the JSON schema for a widget type |
widgets:list | List widgets — --page --limit --project --search --type |
widget:get <id> | Get a widget (type + data) |
widget:create | Create a widget — --type --data --name --project |
widget:update <id> | Set a widget's data — --data |
widget:delete <id> | Delete a widget |
widget:embed <id> | Get the embed code |
widget:editor <id> | Get the editor URL |
projects:list | List projects — --page --limit |
project:get <id> | Get project details |
contacts:list <projectId> | List a project's contacts — --page --limit |
contact:get <projectId> <contactId> | Get a contact |
submissions:list <projectId> | List submissions — --page --limit --widget |
submission:get <projectId> <submissionId> | Get a submission |
analytics <widgetId> | Widget analytics — --from --to --breakdown --events |
help | Show usage |
Using it from an agent
Because output is always JSON and the surface is small, the CLI is well-suited to agent pipelines (e.g. OpenClaw, Claude Code). A typical flow:
commonninja widget-types # discover types
commonninja widget-schema reviews # get the schema
commonninja widget:create --type reviews --data @data.json # create
commonninja widget:embed <widgetId> # return embed code
For chat assistants (Claude, ChatGPT, Cursor), the hosted MCP server is usually simpler — connect a URL and ask in plain language. Use the CLI when you want scriptable, JSON-in/JSON-out automation.