CLI

This package provides a convenient interface to query the MagicBell API.

Quick Start

To get started, install the package with npm

npm install -g magicbell-cli

Usage

The CLI needs to be configured with your email, project's JWT, API Key and Secret Key, which are available in the MagicBell Dashboard. Please run `magicbell login` to set up your credentials.

magicbell login \
	--email jane@example.com \
	--jwt ey...CU \
	--api-key 5f...58 \
	--secret-key r4...6m
	

Commands

Below you'll find the all supported commands with their arguments. Note that you can also run magicbell at any time to get a list of options in your console.

You can pass data for commands that take a request body with a --data flag.

broadcast

create

Creates a new broadcast. When a broadcast is created, it generates individual notifications for relevant users within the project.

magicbell broadcast create

list

Retrieves a paginated list of broadcasts for the project. Returns basic information about each broadcast including its creation time and status.

magicbell broadcast list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch

Retrieves detailed information about a specific broadcast by its ID. Includes the broadcast's configuration and current status.

magicbell broadcast fetch

Flags

Name	Required
broadcast_id	true

channel

list_teams_tokens

Lists all Teams tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_teams_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch_web_push_token

Fetches details of a specific Web Push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_web_push_token

Flags

Name	Required
token_id	true

list_expo_tokens

Lists all Expo tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_expo_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

delete_expo_token

Deletes one of the authenticated user's Expo tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_expo_token

Flags

Name	Required
token_id	true

fetch_teams_token

Fetches details of a specific Teams token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_teams_token

Flags

Name	Required
token_id	true

save_apns_token

Saves the APNs token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_apns_token

save_expo_token

Saves the Expo token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_expo_token

save_user_preferences

Save a user's channel preferences.

magicbell channel save_user_preferences

list_web_push_tokens

Lists all Web Push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_web_push_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

delete_apns_token

Deletes one of the authenticated user's APNs tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_apns_token

Flags

Name	Required
token_id	true

fetch_expo_token

Fetches details of a specific Expo token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_expo_token

Flags

Name	Required
token_id	true

save_inbox_token

Saves the Inbox token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_inbox_token

delete_inbox_token

Deletes one of the authenticated user's Inbox tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_inbox_token

Flags

Name	Required
token_id	true

save_fcm_token

Saves the FCM token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_fcm_token

list_fcm_tokens

Lists all FCM tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_fcm_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch_config

Fetches the channels config for a given key.

magicbell channel fetch_config

Flags

Name	Required
key	true

fetch_fcm_token

Fetches details of a specific FCM token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_fcm_token

Flags

Name	Required
token_id	true

list_slack_tokens

Lists all Slack tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_slack_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch_slack_token

Fetches details of a specific Slack token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_slack_token

Flags

Name	Required
token_id	true

delete_web_push_token

Deletes one of the authenticated user's Web Push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_web_push_token

Flags

Name	Required
token_id	true

list_apns_tokens

Lists all APNs tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_apns_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

delete_fcm_token

Deletes one of the authenticated user's FCM tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_fcm_token

Flags

Name	Required
token_id	true

save_slack_token

Saves the Slack token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_slack_token

delete_teams_token

Deletes one of the authenticated user's Teams tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_teams_token

Flags

Name	Required
token_id	true

list_inbox_tokens

Lists all Inbox tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

magicbell channel list_inbox_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch_apns_token

Fetches details of a specific APNs token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_apns_token

Flags

Name	Required
token_id	true

fetch_user_preferences

Fetch a user's channel delivery preferences.

magicbell channel fetch_user_preferences

save_web_push_token

Saves the Web Push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_web_push_token

save_config

Save the channels configuration for a given key.

magicbell channel save_config

fetch_inbox_token

Fetches details of a specific Inbox token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

magicbell channel fetch_inbox_token

Flags

Name	Required
token_id	true

delete_slack_token

Deletes one of the authenticated user's Slack tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

magicbell channel delete_slack_token

Flags

Name	Required
token_id	true

save_teams_token

Saves the Teams token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

magicbell channel save_teams_token

event

list

Retrieves a paginated list of events for the project.

magicbell event list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

fetch

Fetches a project event by its ID.

magicbell event fetch

Flags

Name	Required
event_id	true

integration

save_apns

Updates or creates the APNs integration for the project.

magicbell integration save_apns

save_expo

Updates or creates the Expo integration for the project.

magicbell integration save_expo

list_expo

Retrieves the current Expo integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_expo

delete_fcm

Deletes the FCM integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_fcm

Flags

Name	Required
id	false

save_inbox

Updates or creates the Inbox integration for the project.

magicbell integration save_inbox

save_slack

Updates or creates the Slack integration for the project.

magicbell integration save_slack

save_slack_installation

Creates a new installation of a Slack integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

magicbell integration save_slack_installation

delete_stripe

Deletes the Stripe integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_stripe

Flags

Name	Required
id	false

list

Lists all available and configured integrations for the project. Returns a summary of each integration including its type, status, and basic configuration information.

magicbell integration list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

save_github

Updates or creates the GitHub integration for the project.

magicbell integration save_github

delete_mailgun

Deletes the Mailgun integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_mailgun

Flags

Name	Required
id	false

delete_ping_email

Deletes the Ping Email integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_ping_email

Flags

Name	Required
id	false

save_sendgrid

Updates or creates the SendGrid integration for the project.

magicbell integration save_sendgrid

start_slack_installation

Initiates the installation flow for a Slack integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

magicbell integration start_slack_installation

list_stripe

Retrieves the current Stripe integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_stripe

list_twilio

Retrieves the current Twilio integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_twilio

list_github

Retrieves the current GitHub integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_github

list_inbox

Retrieves the current Inbox integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_inbox

list_ping_email

Retrieves the current Ping Email integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_ping_email

delete_slack

Deletes the Slack integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_slack

Flags

Name	Required
id	false

delete_twilio

Deletes the Twilio integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_twilio

Flags

Name	Required
id	false

delete_web_push

Deletes the Web Push integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_web_push

Flags

Name	Required
id	false

save_web_push_installation

Creates a new installation of a Web Push integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

magicbell integration save_web_push_installation

delete_expo

Deletes the Expo integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_expo

Flags

Name	Required
id	false

list_mailgun

Retrieves the current Mailgun integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_mailgun

save_ping_email

Updates or creates the Ping Email integration for the project.

magicbell integration save_ping_email

list_ses

Retrieves the current Amazon SES integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_ses

save_twilio

Updates or creates the Twilio integration for the project.

magicbell integration save_twilio

list_web_push

Retrieves the current Web Push integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_web_push

save_eventsource

Updates or creates the EventSource integration for the project.

magicbell integration save_eventsource

save_inbox_installation

Creates a new installation of a Inbox integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

magicbell integration save_inbox_installation

save_stripe

Updates or creates the Stripe integration for the project.

magicbell integration save_stripe

save_web_push

Updates or creates the Web Push integration for the project.

magicbell integration save_web_push

start_web_push_installation

Initiates the installation flow for a Web Push integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

magicbell integration start_web_push_installation

delete_eventsource

Deletes the EventSource integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_eventsource

Flags

Name	Required
id	false

list_fcm

Retrieves the current FCM integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_fcm

delete_github

Deletes the GitHub integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_github

Flags

Name	Required
id	false

start_inbox_installation

Initiates the installation flow for an Inbox integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

magicbell integration start_inbox_installation

save_mailgun

Updates or creates the Mailgun integration for the project.

magicbell integration save_mailgun

delete_ses

Deletes the Amazon SES integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_ses

Flags

Name	Required
id	false

list_slack

Retrieves the current Slack integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_slack

finish_slack_installation

Completes the installation flow for the Slack integration. This endpoint is typically called after the user has completed any required authorization steps with Slack.

magicbell integration finish_slack_installation

list_apns

Retrieves the current APNs integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_apns

list_eventsource

Retrieves the current EventSource integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_eventsource

save_fcm

Updates or creates the FCM integration for the project.

magicbell integration save_fcm

delete_sendgrid

Deletes the SendGrid integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_sendgrid

Flags

Name	Required
id	false

list_sendgrid

Retrieves the current SendGrid integration configurations for a specific integration type in the project. Returns configuration details and status information.

magicbell integration list_sendgrid

delete_apns

Deletes the APNs integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_apns

Flags

Name	Required
id	false

delete_inbox

Deletes the Inbox integration configuration from the project. This will disable the integration's functionality within the project.

magicbell integration delete_inbox

Flags

Name	Required
id	false

save_ses

Updates or creates the Amazon SES integration for the project.

magicbell integration save_ses

notification

archive

Archive a notification.

magicbell notification archive

Flags

Name	Required
notification_id	true

mark_read

Marks a notification as read.

magicbell notification mark_read

Flags

Name	Required
notification_id	true

unarchive

Unarchives a notification.

magicbell notification unarchive

Flags

Name	Required
notification_id	true

mark_unread

Marks a notification as unread.

magicbell notification mark_unread

Flags

Name	Required
notification_id	true

list

Lists all notifications for a user.

magicbell notification list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false
status	false
category	false
topic	false

archive_all

Archive all notifications.

magicbell notification archive_all

Flags

Name	Required
category	false
topic	false

mark_all_read

Marks all notifications as read.

magicbell notification mark_all_read

Flags

Name	Required
category	false
topic	false

fetch

Gets a notification by ID.

magicbell notification fetch

Flags

Name	Required
notification_id	true

user

list

Lists all users in the project.

magicbell user list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false
query	false

delete_apns_token

Deletes a specific user's APNs token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_apns_token

Flags

Name	Required
user_id	true
token_id	true

list_web_push_tokens

Lists all Web Push tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_web_push_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

delete_web_push_token

Deletes a specific user's Web Push token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_web_push_token

Flags

Name	Required
user_id	true
token_id	true

fetch_web_push_token

Fetches a specific Web Push token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_web_push_token

Flags

Name	Required
user_id	true
token_id	true

save

Creates or updates a user with the provided details. The user will be associated with the project specified in the request context.

magicbell user save

delete

Removes a user and all associated data from the project.

magicbell user delete

Flags

Name	Required
user_id	true

list_inbox_tokens

Lists all Inbox tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_inbox_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

list_expo_tokens

Lists all Expo tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_expo_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

fetch_expo_token

Fetches a specific Expo token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_expo_token

Flags

Name	Required
user_id	true
token_id	true

list_teams_tokens

Lists all Teams tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_teams_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

delete_inbox_token

Deletes a specific user's Inbox token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_inbox_token

Flags

Name	Required
user_id	true
token_id	true

delete_expo_token

Deletes a specific user's Expo token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_expo_token

Flags

Name	Required
user_id	true
token_id	true

delete_fcm_token

Deletes a specific user's FCM token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_fcm_token

Flags

Name	Required
user_id	true
token_id	true

fetch_fcm_token

Fetches a specific FCM token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_fcm_token

Flags

Name	Required
user_id	true
token_id	true

delete_slack_token

Deletes a specific user's Slack token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_slack_token

Flags

Name	Required
user_id	true
token_id	true

fetch_inbox_token

Fetches a specific Inbox token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_inbox_token

Flags

Name	Required
user_id	true
token_id	true

list_apns_tokens

Lists all APNs tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_apns_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

fetch_apns_token

Fetches a specific APNs token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_apns_token

Flags

Name	Required
user_id	true
token_id	true

list_fcm_tokens

Lists all FCM tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_fcm_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

list_slack_tokens

Lists all Slack tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

magicbell user list_slack_tokens

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

fetch_slack_token

Fetches a specific Slack token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_slack_token

Flags

Name	Required
user_id	true
token_id	true

delete_teams_token

Deletes a specific user's Teams token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

magicbell user delete_teams_token

Flags

Name	Required
user_id	true
token_id	true

fetch_teams_token

Fetches a specific Teams token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

magicbell user fetch_teams_token

Flags

Name	Required
user_id	true
token_id	true

workflow

save

Creates or updates a workflow definition for the project

magicbell workflow save

fetch

Retrieves a workflow definition by key

magicbell workflow fetch

create_run

Executes a workflow with the provided input parameters

magicbell workflow create_run

fetch_run

Retrieves the status and details of a workflow run

magicbell workflow fetch_run

Flags

Name	Required
run_id	true

list_runs

Retrieves all runs for a specific workflow

magicbell workflow list_runs

Flags

Name	Required
workflow_key	true