Use the ActivitySmith CLI to send push notifications, update widgets, and manage Live Activities from shell scripts, CI pipelines, and terminal workflows.
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.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.
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.
stats: best for business or product stats like revenue, number of users, conversion, uptime, or any metric set you want visible at a glance
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.
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.
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
Keep your key numbers on your Lock Screen. stats fits up to 8 labeled values,
such as revenue, orders, conversion, uptime, or any other business metric you
want visible at a glance. Each metric can use a formatted string or number as
its value. Add color to a metric to show an accent dot next to its label;
omit color to show the label without a dot.
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.
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.
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.
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.
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.
What will work:
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.
