CLI | ActivitySmith

Installation

Install the ActivitySmith CLI globally with npm:

CLI

# Install globally with npm
npm install -g activitysmith-cli

Usage

Create an API key
Authenticate with ACTIVITYSMITH_API_KEY or pass --api-key per command.
Run activitysmith --help to inspect available commands.

Use the environment variable when you want the cleanest shell scripts:

CLI

export ACTIVITYSMITH_API_KEY="YOUR-API-KEY"

activitysmith --help

Or pass the key directly:

CLI

activitysmith --api-key "YOUR-API-KEY" push --title "Hello"

Commands

Push Notification

Use activitysmith push when a deploy fails, a CI run finishes, or a background job needs attention. Push notification example

CLI

activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --subtitle "main"

Rich Push Notifications with Media

CLI

activitysmith push \
  --title "Homepage ready" \
  --message "Your agent finished the redesign." \
  --media "https://cdn.example.com/output/homepage-v2.png" \
  --redirection "https://github.com/acme/web/pull/482"

Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content. Rich push notification with audio

What will work:

direct image URL: .jpg, .png, .gif, etc.
direct audio file URL: .mp3, .m4a, etc.
direct video file URL: .mp4, .mov, etc.
URL that responds with a proper media Content-Type, even if the path has no extension

--media can be combined with --redirection, but not with --actions.

Actionable Push Notifications

Actionable push notification with redirection and actions

Push notification redirection and actions are optional and can be used to redirect the user to a specific URL when they tap the notification or to trigger a specific action when they long-press the notification. Webhooks are executed by ActivitySmith backend.

CLI

activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --redirection "https://github.com/org/repo/actions/runs/123456789" \
  --actions '[
    {
      "title": "Open Failing Run",
      "type": "open_url",
      "url": "https://github.com/org/repo/actions/runs/123456789"
    },
    {
      "title": "Create Incident",
      "type": "webhook",
      "url": "https://hooks.example.com/incidents/create",
      "method": "POST",
      "body": {
        "service": "payments-api",
        "severity": "high",
        "source": "activitysmith-cli"
      }
    }
  ]'

You can also load actions from a file:

CLI

activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --actions-file "./actions.json"

Live Activities

Metrics Live Activity screenshot

There are three types of Live Activities:

metrics: best for live operational stats like server CPU and memory, queue depth, or replica lag
segmented_progress: best for step-based workflows like deployments, backups, and ETL pipelines
progress: best for continuous jobs like uploads, reindexes, and long-running migrations tracked as a percentage

When working with Live Activities via our API, you have two approaches tailored to different needs. First, the stateless mode is the simplest path - one API call can initiate or update an activity, and another ends it - no state tracking on your side. This is ideal if you want minimal complexity, perfect for automated workflows like cron jobs. In contrast, if you need precise lifecycle control, the classic approach offers distinct calls for start, updates, and end, giving you full control over the activity’s state. In the following sections, we’ll break down how to implement each method so you can choose what fits your use case best.

Simple: Let ActivitySmith manage the Live Activity for you

Use a stable stream_key to identify the system or workflow you are tracking, such as a server, deployment, build pipeline, cron job, or charging session. This is especially useful for cron jobs and other scheduled tasks where you do not want to store activity_id between runs.

Metrics

Metrics stream example

activitysmith activity stream prod-web-1 \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 9, "unit": "%" },
      { "label": "MEM", "value": 45, "unit": "%" }
    ]
  }'

Segmented progress

Segmented progress stream example

activitysmith activity stream nightly-backup \
  --content-state '{
    "title": "Nightly Backup",
    "subtitle": "upload archive",
    "type": "segmented_progress",
    "numberOfSteps": 3,
    "currentStep": 2
  }'

Progress

Progress stream example

activitysmith activity stream search-reindex \
  --content-state '{
    "title": "Search Reindex",
    "subtitle": "catalog-v2",
    "type": "progress",
    "percentage": 42
  }'

Run activitysmith activity stream <stream-key> ... again with the same stream_key whenever the state changes.

End a stream

Use this when the tracked process is finished and you no longer want the Live Activity on devices. content_state is optional here; include it if you want to end the stream with a final state.

activitysmith activity end-stream prod-web-1 \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 7, "unit": "%" },
      { "label": "MEM", "value": 38, "unit": "%" }
    ]
  }'

If you later send another activity stream request with the same stream_key, ActivitySmith starts a new Live Activity for that stream again. Stream responses include an operation field:

started: ActivitySmith started a new Live Activity for this stream_key
updated: ActivitySmith updated the current Live Activity
rotated: ActivitySmith ended the previous Live Activity and started a new one
noop: the incoming state matched the current state, so no update was sent
paused: the stream is paused, so no Live Activity was started or updated
ended: returned by activity end-stream after the stream is ended

Advanced: Full lifecycle control

Use these commands when you want to manage the Live Activity lifecycle yourself:

Run activitysmith activity start ....
Save the returned activity_id.
Run activitysmith activity update ... as progress changes.
Run activitysmith activity end ... when the work is finished.

You can use --content-state <json> for the examples below, or build the same payload with flags as documented in Content State Options.

Metrics Type

Use metrics when you want to keep a small set of live stats visible, such as server health, queue pressure, or database load.

Start

Metrics start example

activitysmith activity start \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 9, "unit": "%" },
      { "label": "MEM", "value": 45, "unit": "%" }
    ]
  }'

Update

Metrics update example

activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 76, "unit": "%" },
      { "label": "MEM", "value": 52, "unit": "%" }
    ]
  }'

End

Metrics end example

activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 7, "unit": "%" },
      { "label": "MEM", "value": 38, "unit": "%" }
    ],
    "autoDismissMinutes": 2
  }'

Segmented Progress Type

Use segmented_progress for jobs and workflows that move through clear steps or phases. It fits jobs like deployments, backups, ETL pipelines, and checklists. numberOfSteps is dynamic, so you can increase or decrease it later if the workflow changes.

Start

Segmented progress start example

activitysmith activity start \
  --content-state '{
    "title": "Nightly database backup",
    "subtitle": "create snapshot",
    "numberOfSteps": 3,
    "currentStep": 1,
    "type": "segmented_progress",
    "color": "yellow"
  }'

Update

Segmented progress update example

activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "Nightly database backup",
    "subtitle": "upload archive",
    "numberOfSteps": 3,
    "currentStep": 2
  }'

End

Segmented progress end example

activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "Nightly database backup",
    "subtitle": "verify restore",
    "numberOfSteps": 3,
    "currentStep": 3,
    "autoDismissMinutes": 2
  }'

Progress Type

Use progress when the state is naturally continuous. It fits charging, downloads, sync jobs, uploads, timers, and any flow where a percentage or numeric range is the clearest signal.

Start

Progress start example

activitysmith activity start \
  --content-state '{
    "title": "EV Charging",
    "subtitle": "Added 30 mi range",
    "type": "progress",
    "percentage": 15
  }'

Update

Progress update example

activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "EV Charging",
    "subtitle": "Added 120 mi range",
    "percentage": 60
  }'

End

Progress end example

activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "EV Charging",
    "subtitle": "Added 200 mi range",
    "percentage": 100,
    "autoDismissMinutes": 2
  }'

Live Activity Action

Just like Actionable Push Notifications, Live Activities can have a button that opens provided URL in a browser or triggers a webhook. Webhooks are executed by the ActivitySmith backend. Live Activity with action

Open URL action

CLI

activitysmith activity start \
  --content-state '{
    "title": "Deploying payments-api",
    "subtitle": "Running database migrations",
    "numberOfSteps": 5,
    "currentStep": 3,
    "type": "segmented_progress"
  }' \
  --action '{
    "title": "Open Workflow",
    "type": "open_url",
    "url": "https://github.com/acme/payments-api/actions/runs/1234567890"
  }'

Webhook action

CLI

activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "Reindexing product search",
    "subtitle": "Shard 7 of 12",
    "numberOfSteps": 12,
    "currentStep": 7
  }' \
  --action '{
    "title": "Pause Reindex",
    "type": "webhook",
    "url": "https://ops.example.com/hooks/search/reindex/pause",
    "method": "POST",
    "body": {
      "job_id": "reindex-2026-03-19",
      "requested_by": "activitysmith-cli"
    }
  }'

Content State

For activity start, activity update, and activity end, you can pass 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, --percentage, --value, --upper-limit, --color, --step-color, --auto-dismiss-minutes

Live Activity action options:

--action '{...}'
--action-file path/to/action.json

Use camelCase keys in JSON, for example numberOfSteps, currentStep, and autoDismissMinutes. When the payload gets long, format the JSON across multiple lines or move it to --content-state-file.

Required Fields

activity start: --title, --type, plus either --number-of-steps and --current-step, or --percentage, or --value with --upper-limit
activity update: --title, plus either --current-step, or --percentage, or --value with --upper-limit
activity end: --title, plus either --current-step, or --percentage, or --value with --upper-limit

Field Reference

Field	Description
`title`	Primary label shown in the Live Activity.
`subtitle`	Secondary label shown in the Live Activity.
`type`	Layout type: `segmented_progress` or `progress`.
`numberOfSteps`	Total steps in a segmented progress flow.
`currentStep`	Current step index for segmented progress, starting at `1`.
`percentage`	Progress value from `0` to `100`.
`value`	Current numeric progress value when you want a custom range.
`upperLimit`	Maximum numeric progress value used with `value`.
`color`	Accent color (`lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`).
`stepColor`	Segment color for `segmented_progress` (same values as `color`).
`autoDismissMinutes`	Minutes before dismissal after ending. Default `3`, use `0` for immediate dismissal.

Channels

Use --channels to target specific channels for push and activity start.

CLI

activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --channels "devs,ops"

CLI

activitysmith activity start \
  --title "Nightly database backup" \
  --type segmented_progress \
  --number-of-steps 4 \
  --current-step 1 \
  --channels "devs,ops"

Output

Use --json for machine-readable output:

CLI

activitysmith push --title "Hello" --json

Error Handling

The CLI exits non-zero on non-2xx responses and prints the API error body. That includes validation failures, rate limits, and Live Activity limit errors.

Overall

Official

Resources

​Installation

​Usage

​Commands

​Push Notification

​Rich Push Notifications with Media

​Actionable Push Notifications

​Live Activities

​Simple: Let ActivitySmith manage the Live Activity for you

​Metrics

​Segmented progress

​Progress

​End a stream

​Advanced: Full lifecycle control

​Metrics Type

​Start

​Update

​End

​Segmented Progress Type

​Start

​Update

​End

​Progress Type

​Start

​Update

​End

​Live Activity Action

​Open URL action

​Webhook action

​Content State

​Required Fields

​Field Reference

​Channels

​Output

​Error Handling

​Additional Resources

NPM Package

Source Code

Installation

Usage

Commands

Push Notification

Rich Push Notifications with Media

Actionable Push Notifications

Live Activities

Simple: Let ActivitySmith manage the Live Activity for you

Metrics

Segmented progress

Progress

End a stream

Advanced: Full lifecycle control

Metrics Type

Start

Update

End

Segmented Progress Type

Start

Update

End

Progress Type

Start

Update

End

Live Activity Action

Open URL action

Webhook action

Content State

Required Fields

Field Reference

Channels

Output

Error Handling

Additional Resources