CLI

Installation

Install the ActivitySmith CLI globally with npm:

CLI

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

Agent Skill

Install the ActivitySmith skill when you want Codex, Claude, Cursor, or another skills-compatible agent to decide which ActivitySmith CLI command to run.

CLI

npx -y skills@latest add ActivitySmithHQ/activitysmith-cli --skill activitysmith

Use the skill when an agent should notify you with push notifications, include a notification tap or action that can open a URL or run a specific iPhone Shortcut, or keep task progress visible with Live Activities. For example, a Codex agent can work on your computer, send a push notification when it needs your attention, and include a Shortcut action that runs an OpenChatGPT Shortcut on your iPhone so you can continue the conversation in the ChatGPT app.

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. --redirection can be an HTTPS URL or a shortcuts://run-shortcut?name=... URL.

Actionable Push Notifications

Actionable push notification with redirection and actions

Push notification redirection can open an HTTPS URL or run a specific iPhone Shortcut with a shortcuts://run-shortcut?name=... URL when someone taps the notification. For expanded notification actions, open_url supports HTTPS URLs and shortcuts://run-shortcut?name=... URLs. Webhooks are executed by the ActivitySmith backend and must use HTTPS.

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 Build",
      "type": "open_url",
      "url": "https://github.com/org/repo/actions/runs/123456789"
    },
    {
      "title": "Chat with Jarvis",
      "type": "open_url",
      "url": "shortcuts://run-shortcut?name=Jarvis"
    },
    {
      "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

There are six types of Live Activities:

stats: best for showing business numbers side by side, such as revenue, sales, new users, conversion, refunds, or any other value you want visible at a glance
metrics: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
segmented_progress: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
progress: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
alert: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
timer: use it when you need countdowns or timers

Start & Update Live Activity

Use a stable stream_key to identify the metric, job, deployment, or system you want to keep visible. The first activity stream command starts the Live Activity. Later commands with the same stream_key update it.

Stats

Stats Live Activity stream example

CLI

activitysmith activity stream sales-hourly \
  --content-state '{
    "title": "Sales",
    "subtitle": "last hour",
    "type": "stats",
    "metrics": [
      { "label": "Revenue", "value": "$2430", "color": "blue" },
      { "label": "Orders", "value": "37", "color": "green" },
      { "label": "Conversion", "value": "4.8%", "color": "magenta" },
      { "label": "Avg Order", "value": "$65.68", "color": "yellow" },
      { "label": "Refunds", "value": "$84", "color": "red" },
      { "label": "New Buyers", "value": "18", "color": "cyan" }
    ]
  }'

Metrics

Metrics Live Activity stream example

CLI

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 Live Activity stream example

CLI

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

Progress

Progress Live Activity stream example

CLI

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

Alert

Alert Live Activity stream example

CLI

activitysmith activity stream customer-ops \
  --content-state '{
    "title": "Reactivation",
    "message": "Lumen came back after 2 weeks",
    "type": "alert",
    "icon": {
      "symbol": "cloud.sun",
      "color": "yellow"
    },
    "badge": {
      "title": "Customer",
      "color": "magenta"
    }
  }'

Timer

Timer Live Activity stream example

CLI

activitysmith activity stream benchmark-run \
  --content-state '{
    "title": "Benchmark Run",
    "subtitle": "sampling",
    "type": "timer",
    "duration_seconds": 300,
    "color": "cyan"
  }'

For a countdown, send duration_seconds. You can update title, subtitle, color, or any other visible field as the work changes. Leave duration_seconds out unless you want to change the timer. To start at 00:00 and count up, set counts_down to false and leave out duration_seconds.

End Live Activity

Call activity end-stream with the same stream_key to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set autoDismissMinutes to choose a different dismissal time, including 0 for immediate dismissal.

CLI

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": "%" }
    ],
    "autoDismissMinutes": 2
  }'

Icons and Badges

Add more context to Live Activities with icons and badges.

Icon

Supported Live Activity types: stats, metrics, progress, segmented_progress, alert, and timer.

activitysmith activity stream prod-web-1 \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "icon": { "symbol": "server.rack", "color": "blue" },
    "metrics": [
      { "label": "CPU", "value": 18, "unit": "%" },
      { "label": "MEM", "value": 42, "unit": "%" }
    ]
  }'

The icon.symbol value is an Apple SF Symbol name. Browse the catalog with one of these tools:

ActivitySmith app - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
SF Symbols - Apple’s official macOS app
Interactful - free third-party iOS app listing all SF Symbols under Foundations -> Iconography

Badge

Badges are supported by alert, progress, and segmented_progress Live Activities.

activitysmith activity stream nightly-database-backup \
  --content-state '{
    "title": "Nightly Database Backup",
    "subtitle": "verify restore",
    "type": "progress",
    "badge": { "title": "S3", "color": "cyan" },
    "percentage": 62
  }'

Live Activity Colors

Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge: lime, green, cyan, blue, purple, magenta, red, orange, yellow, gray

Live Activity Action

Metrics Live Activity with action

Live Activities can include an action button.

open_url: open an HTTPS URL.
open_url with a shortcuts://run-shortcut?name=... URL: run a specific iPhone Shortcut, for example to open an app.
webhook: trigger a backend GET/POST workflow.

Open URL action

CLI

activitysmith activity stream prod-web-1 \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 76, "unit": "%" },
      { "label": "MEM", "value": 52, "unit": "%" }
    ]
  }' \
  --action '{
    "title": "Dashboard",
    "type": "open_url",
    "url": "https://status.example.com/servers/prod-web-1"
  }'

Apple Shortcut action

CLI

activitysmith activity stream prod-web-1 \
  --content-state '{
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 76, "unit": "%" },
      { "label": "MEM", "value": 52, "unit": "%" }
    ]
  }' \
  --action '{
    "title": "Chat with Jarvis",
    "type": "open_url",
    "url": "shortcuts://run-shortcut?name=Jarvis"
  }'

Webhook action

CLI

activitysmith activity stream search-reindex \
  --content-state '{
    "title": "Reindexing product search",
    "subtitle": "Shard 7 of 12",
    "type": "segmented_progress",
    "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"
    }
  }'

Secondary action

Use --secondary-action when you want a second button beside the primary --action. The secondary action button is supported for alert, progress, and segmented_progress Live Activities. Both buttons use the same open_url, webhook, and Apple Shortcut payload shapes.

CLI

activitysmith activity stream agent-approval \
  --content-state '{
    "title": "Approval Needed",
    "message": "Should I send the follow-up email to Brightlane?",
    "type": "alert",
    "color": "green",
    "icon": { "symbol": "sparkles", "color": "green" },
    "badge": { "title": "Agent", "color": "green" }
  }' \
  --action '{
    "title": "Send",
    "type": "webhook",
    "url": "https://agent.example.com/live-activity/approve",
    "method": "POST",
    "body": {
      "approval_id": "approval_01JY3J7Q9S0P8M1V5PZK7DR4M2",
      "decision": "send"
    }
  }' \
  --secondary-action '{
    "title": "Deny",
    "type": "webhook",
    "url": "https://agent.example.com/live-activity/deny",
    "method": "POST",
    "body": {
      "approval_id": "approval_01JY3J7Q9S0P8M1V5PZK7DR4M2",
      "decision": "deny"
    }
  }'

Channels

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

CLI

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

CLI

activitysmith activity stream nightly-backup \
  --content-state '{
    "title": "Nightly database backup",
    "type": "segmented_progress",
    "numberOfSteps": 4,
    "currentStep": 1
  }' \
  --channels "devs,ops"

Widgets

Lock screen widgets

ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the web app, then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.

Use the metric key to update its value.

activitysmith metrics update deploy.success_rate 99.9

String metric values work too.

activitysmith metrics update prod.status healthy

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.

Installation

Agent Skill

Usage

Commands

Push Notification

Rich Push Notifications with Media

Actionable Push Notifications

Live Activities

Start & Update Live Activity

Stats

Metrics

Segmented Progress

Progress

Alert

Timer

End Live Activity

Icons and Badges

Icon

Badge

Live Activity Colors

Live Activity Action

Open URL action

Apple Shortcut action

Webhook action

Secondary action

Channels

Widgets

Output

Error Handling

Additional Resources

NPM Package

Source Code

​Installation

​Agent Skill

​Usage

​Commands

​Push Notification

​Rich Push Notifications with Media

​Actionable Push Notifications

​Live Activities

​Start & Update Live Activity

​Stats

​Metrics

​Segmented Progress

​Progress

​Alert

​Timer

​End Live Activity

​Icons and Badges

​Icon

​Badge

​Live Activity Colors

​Live Activity Action

​Open URL action

​Apple Shortcut action

​Webhook action

​Secondary action

​Channels

​Widgets

​Output

​Error Handling

​Additional Resources

NPM Package

Source Code

Installation

Agent Skill

Usage

Commands

Push Notification

Rich Push Notifications with Media

Actionable Push Notifications

Live Activities

Start & Update Live Activity

Stats

Metrics

Segmented Progress

Progress

Alert

Timer

End Live Activity

Icons and Badges

Icon

Badge

Live Activity Colors

Live Activity Action

Open URL action

Apple Shortcut action

Webhook action

Secondary action

Channels

Widgets

Output

Error Handling

Additional Resources