@servicem8/addon-kit

Build, test, and deploy ServiceM8 add-ons from your terminal.

addon-kit is the command-line tool for the ServiceM8 Addon SDK. Scaffold an add-on, deploy it to the platform, and manage its secrets — without leaving your editor.

npx addon-kit init my-addon    # scaffold an add-on project
cd my-addon
npx addon-kit login            # authenticate in your ServiceM8 browser
npx addon-kit deploy           # ship it — live on your account in seconds

Installation

npm install -D @servicem8/addon-kit      # per-project (recommended)
# or
npm install -g @servicem8/addon-kit      # global

Requires Node.js 22+.

Coding agent skills

The package includes the servicem8-addon-kit skill in skills/. Install it into supported coding agents' global skill directories with:

npx addon-kit --install-skills

The flag also works alongside a command and installs skills before that command. It detects agents by their home directories, copies the bundled skill without network access, and replaces that skill on subsequent runs. Other skills and files are left alone. Symlinked skill directories/files are not replaced. With no detected agents, it reports that nothing was installed.

Supported agents: Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, Cline, Continue, Roo, Goose, and Kilo Code.

Installation prints a hint when a detected agent is missing the skill. This notice never waits for input or installs skills automatically. npm hides successful dependency lifecycle output by default; to see the notice in captured agent output:

npm install --save-dev @servicem8/addon-kit@latest --foreground-scripts

With a plain npm install, the hook still runs but npm may hide its output. --ignore-scripts skips it altogether. Normal CLI commands repeat the hint on stderr while the skill is missing, including in non-interactive sessions. After updating Addon Kit, rerun npx addon-kit --install-skills to refresh the skill.

Commands

| Command | What it does | |---------|--------------| | addon-kit init [name] | Scaffold a new add-on project (TypeScript by default): addon.jsonc, an entry-point function, package.json. In a directory with a legacy manifest.json, offers an automatic migration. | | addon-kit login | Open your browser to authorize Addon Kit with OAuth. Tokens are stored in ~/.sm8/ and refreshed automatically. Use --api-key for the existing API-key prompt. | | addon-kit logout | Remove local credentials. OAuth authorization on ServiceM8 is not revoked. | | addon-kit whoami | Show the authenticated account and OAuth scopes or API-key access level. | | addon-kit deploy | Validate addon.jsonc, bundle your entry point (TypeScript, multiple files and npm dependencies all supported), and deploy. The add-on is activated on your account immediately. --dry-run validates and bundles without deploying. | | addon-kit secret put/list/delete <NAME> | Manage add-on secrets. Secrets are delivered to your function as environment variables and apply immediately — no redeploy. Values are prompted, never passed as arguments. |

Every command documents itself: addon-kit <command> --help.

Live logs

Run addon-kit tail from your add-on project to stream its deployed function logs until Ctrl+C. The command targets exactly one add-on: the slug in addon.jsonc. Use --cwd or --config to select a different project. Extra addon IDs and log group lists are rejected.

addon-kit tail
addon-kit tail --filter '"ERROR"'
addon-kit tail --format json

Uses your existing ServiceM8 login (OAuth manage_addons or a full-access API key). No AWS CLI installation or AWS account configuration is needed. ServiceM8 verifies ownership and streams logs over an authenticated SSE connection. AWS credentials stay on ServiceM8 servers. Logs include the add-on's executions across runtime regions and installing accounts.

Log events go to stdout; connection status and sampling notices go to stderr. JSON mode emits one event per line, including timestamps, message, and log stream name. Pretty mode removes terminal control sequences from messages.

This command streams newly ingested logs, with centralization delivery delay. It does not fetch history. It reconnects with fresh ServiceM8 authentication after each five-minute session or a connection interruption; events during reconnect gaps are not replayed. CloudWatch can sample high-volume streams. If a log group does not exist yet, invoke the deployed function and retry after log delivery. Up to two tails can run per developer account per platform region.

Addon Kit 1.3.0 requires the platform SSE log endpoint. Deploy the platform update before publishing this CLI version. Older CLI versions must upgrade once the endpoint changes.

Browser authentication

npx addon-kit login
npx addon-kit whoami
npx addon-kit deploy

Login opens ServiceM8 in your default browser and asks permission to manage your add-ons. It uses S256 PKCE and a temporary HTTP callback at http://localhost:8976/oauth/callback, matching Wrangler. Login times out after two minutes. No API key or client secret needs to be copied.

Use --browser=false to open the printed URL manually. The browser must be able to reach the CLI machine's callback port. If port 8976 is occupied, use --callback-port 8977; ServiceM8's dynamic registration allows Addon Kit to register that exact callback URL. No device authorization flow is provided yet.

By default, login requests manage_addons. If your function calls customer-data APIs, include the required scopes when logging in and in the add-on manifest, for example:

npx addon-kit login --scopes "read_jobs read_customers"

The platform limits automatic activation to manifest scopes that the deploying credential holds. A deployment token with only manage_addons does not grant your function access to customer data.

Credentials live in ~/.sm8/credentials.json (mode 0600). A public OAuth client registration is cached per CLI installation. Access tokens refresh automatically before expiry; replacement tokens are saved atomically before use. Credential changes and refreshes share a filesystem lock across CLI processes. If a process is forcibly terminated, a subsequent command may report a leftover credentials.lock; remove it only after confirming no Addon Kit command is running.

Existing API-key credentials remain supported. addon-kit login --api-key prompts for a key, and SM8_API_KEY takes precedence for CI. Browser login never starts automatically from deployment commands. logout clears local credentials only: ServiceM8 currently has no OAuth revocation endpoint for the CLI. It does not unset SM8_API_KEY.

SM8_HOME changes the credential directory. OAuth credentials are tied to their SM8_API_BASE_URL; use a separate home when testing against another platform endpoint.

The config file: addon.jsonc

One file per add-on project — your manifest plus tooling settings, with comments:

{
	"$schema": "./node_modules/@servicem8/addon-kit/addon-schema.json",

	// The unique identifier for this add-on (lowercase, digits, hyphens).
	// Deploys upsert on this — changing it creates a NEW add-on.
	"slug": "job-weather",

	// The customer-facing name shown in the Add-on Store.
	"name": "Job Weather Forecast",
	"version": "1.0",

	// Entry point, bundled by addon-kit deploy (defaults to index.js).
	"main": "src/index.ts",

	"actions": [
		{
			"name": "Check Weather",
			"type": "online",
			"entity": "job",
			"iconURL": "https://example.com/icon-512.png",
			"event": "check_weather"
		}
	]
}

The $schema reference gives you validation and autocomplete in your editor. All add-on manifest fields are supported with identical semantics — migrating an existing add-on is renaming manifest.json to addon.jsonc and adding a slug.

Your function

Add-ons run as serverless functions. addon-kit init scaffolds a working handler:

export const handler = async (event: SM8Event) => {
	// event.eventName, event.eventArgs.jobUUID
	// event.auth.accessToken — a short-lived token for the ServiceM8 REST API
	return { eventResponse: "<html>…</html>" };
};

addon-kit deploy bundles whatever your entry point imports — TypeScript, multiple files, npm packages — into a single artifact (up to 45 MB).

CI

# e.g. GitLab CI / GitHub Actions
- npm ci
- SM8_API_KEY=$SM8_API_KEY npx addon-kit deploy

License

MIT © ServiceM8