Skip to main content

​
Installation

Install the ActivitySmith CLI globally using npm:
CLI
# Install globally with npm
npm install -g activitysmith-cli

# Authenticate
export ACTIVITYSMITH_API_KEY="YOUR-API-KEY"

# Verify
activitysmith --status

​
Authentication

Set your API key as an environment variable before running commands:
CLI
export ACTIVITYSMITH_API_KEY="YOUR-API-KEY"
Verify the CLI is installed:
CLI
activitysmith --help

​
Quickstart

Send a push notification:
CLI
activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch"

​
Commands

​
Push Notification

Sends a push notification to every paired device in your account.
CLI
activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --subtitle "main"

​
Live Activity: Start

Start a Live Activity and get back an activityId for updates.
CLI
activitysmith activity start \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"start","numberOfSteps":4,"currentStep":1,"type":"segmented_progress","color":"yellow"}'
Or use flags:
CLI
activitysmith activity start \
  --title "ActivitySmith API Deployment" \
  --subtitle "start" \
  --number-of-steps 4 \
  --current-step 1 \
  --type segmented_progress \
  --color yellow

​
Live Activity: Update

Update an existing Live Activity using its activityId.
CLI
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"npm i & pm2","currentStep":3}'
Or use flags:
CLI
activitysmith activity update \
  --activity-id "<activityId>" \
  --title "ActivitySmith API Deployment" \
  --subtitle "npm i & pm2" \
  --current-step 3

​
Live Activity: End

End a Live Activity and optionally control its dismissal timing.
CLI
activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"done","currentStep":4,"autoDismissMinutes":3}'
Or use flags:
CLI
activitysmith activity end \
  --activity-id "<activityId>" \
  --title "ActivitySmith API Deployment" \
  --subtitle "done" \
  --current-step 4 \
  --auto-dismiss-minutes 3

​
Content State

You can provide content state in two ways:
  • JSON: --content-state '{...}' or --content-state-file path/to/payload.json
  • Flags: --title, --subtitle, --type, --number-of-steps, --current-step, --color, --step-color, --auto-dismiss-minutes
Use camelCase keys in JSON (for example: numberOfSteps, currentStep, autoDismissMinutes).

​
Required Fields

  • activity start: title, numberOfSteps, currentStep, type
  • activity update: title, currentStep
  • activity end: title, currentStep

​
Field Reference

FieldDescription
titlePrimary label shown in the Live Activity.
subtitleSecondary label shown in the Live Activity.
typeLayout type. For now: segmented_progress.
numberOfStepsTotal steps in the progress flow.
currentStepCurrent step index (1-based).
colorAccent color (lime, green, cyan, blue, purple, magenta, red, orange, yellow).
stepColorColor for step segments (same values as color).
autoDismissMinutesMinutes before dismissal after ending (default 3, 0 for immediate).

​
Output

Use --json to output machine-readable JSON.

​
Error Handling

The CLI exits non-zero on non-2xx responses and prints the API error body (for example, rate limit or Live Activity limit errors).