CLI Reference

Mushu CLI - Authentication and push notifications for your apps

Installation

pip install mushu-cli

Global Commands

mushu init

Initialize a .mushu.json config file in the current directory. This creates a project-specific configuration that the CLI will automatically use when running commands from this directory (or any subdirectory). Examples: mushu init --org org_abc123 mushu init --org org_abc123 --tenant tenant_xyz mushu init --org org_abc123 --app app_def456

mushu init

Option	Description
`--org, -o`	Organization ID
`--org-name`	Organization name (for display)
`--app, -a`	App ID
`--app-name`	App name (for display)
`--tenant, -t`	Notification tenant ID
`--pay-tenant`	Pay tenant ID
`--force, -f`	Overwrite existing config

mushu config

Configure global CLI settings. For per-project settings, use 'mushu init' to create a .mushu.json file.

mushu config

Option	Description
`--auth-url`	Set auth API URL
`--notify-url`	Set notify API URL
`--pay-url`	Set pay API URL
`--media-url`	Set media API URL
`--show, -s`	Show current config

mushu status

Show current status and effective configuration.

mushu status

auth commands

Authentication commands

mushu auth login

Sign in with Apple (opens browser). Opens your default browser for Apple Sign In. After authentication, the browser will redirect back to the CLI to complete login.

mushu auth login

Options

Flag	Description
`--no-browser`	Print URL instead of opening browser

mushu auth login-manual

Manually set tokens — for testing or non-interactive use (CI, LLM agents). Tokens can be passed via flags or MUSHU_ACCESS_TOKEN / MUSHU_REFRESH_TOKEN env vars. Examples: mushu auth login-manual --access-token eyJ... --refresh-token eyJ... MUSHU_ACCESS_TOKEN=eyJ... mushu auth login-manual

mushu auth login-manual

Options

Flag	Description
`--access-token`	Access token (skips prompt)
`--refresh-token`	Refresh token (skips prompt)

mushu auth logout

Sign out and clear stored tokens.

mushu auth logout

mushu auth status

Show current authentication status.

mushu auth status

mushu auth token

Display current session token info.

mushu auth token

mushu auth refresh

Refresh session tokens.

mushu auth refresh

mushu auth user

Show current user profile.

mushu auth user

auth-providers commands

Auth provider management (Apple/Google/Facebook Sign-In + legacy migration)

mushu auth-providers create

mushu auth-providers create

Options

Flag	Description
`--provider, -p`	Provider type: apple, google, facebook
`--app, -a`	App ID
`--apple-team-id`	Apple Developer team ID
`--apple-key-id`	Apple Sign-In key ID
`--apple-bundle-ids`	Comma-separated iOS bundle IDs (e.g. com.acme.App,com.acme.AppClip)
`--apple-services-id`	Apple Services ID for web OAuth
`--apple-private-key-file`	Path to Apple Sign-In .p8 private key file
`--google-client-id`
`--google-client-secret-file`
`--facebook-app-id`
`--facebook-app-secret-file`
`--facebook-scopes`	Comma-separated Facebook scopes (e.g. email,public_profile)
`--disabled`	Create as disabled

mushu auth-providers list

List auth providers configured for an app.

mushu auth-providers list

Options

Flag	Description
`--app, -a`	App ID

mushu auth-providers show

Show full details for one auth provider.

mushu auth-providers show

Options

Flag	Description
`--provider, -p`	Provider type
`--app, -a`	App ID

mushu auth-providers delete

Delete an auth provider. Existing sessions stay valid until they expire.

mushu auth-providers delete

Options

Flag	Description
`--provider, -p`	Provider type
`--app, -a`	App ID
`--yes, -y`	Skip confirmation

mushu auth-providers attach-legacy-bridge

Attach a legacy-JWT exchange bridge. Lets existing users' sessions migrate seamlessly — iOS clients POST their legacy JWT to `/auth/legacy-exchange` and receive a mushu session, no re-login.

mushu auth-providers attach-legacy-bridge

Options

Flag	Description
`--provider, -p`	Provider type to attach the bridge to
`--app, -a`	App ID
`--algorithm`	JWT signing algorithm used by your legacy backend ("RS256", "HS256", "ES256", ...)*
`--jwks-url`	JWKS URL for your legacy backend (preferred — works for any provider that exposes one)
`--signing-secret-file`	Path to file containing the shared HS256 signing secret (same-team migrations only)
`--provider-sub-type`	Which mushu provider the legacy JWT `sub` corresponds to ("apple", "google", ...)
`--issuer`	Expected `iss` claim on legacy JWTs
`--audience`	Expected `aud` claim on legacy JWTs

mushu auth-providers detach-legacy-bridge

Detach the legacy-JWT bridge. Run this after migration is complete and no active client still holds a legacy session.

mushu auth-providers detach-legacy-bridge

Options

Flag	Description
`--provider, -p`	Provider type
`--app, -a`	App ID
`--yes, -y`	Skip confirmation

mushu auth-providers verify

Verify tenant is wired up. Checks provider is configured; if a legacy token is provided, exercises /auth/legacy-exchange end-to-end.

mushu auth-providers verify

Options

Flag	Description
`--app, -a`	App ID
`--provider, -p`	Provider type
`--legacy-token-file`	Path to a file containing a real legacy JWT. If provided, /auth/legacy-exchange is exercised.

org commands

Organization management

mushu org create

Create a new organization.

mushu org create <name>

Arguments

Name	Description	Required
`name`	Organization name	Yes

mushu org list

List organizations you belong to.

mushu org list

mushu org show

Show organization details.

mushu org show <org_id>

Arguments

Name	Description	Required
`org_id`	Organization ID	Yes

mushu org use

Set default organization for commands.

mushu org use <org_id>

Arguments

Name	Description	Required
`org_id`	Organization ID to set as default	Yes

mushu org current

Show current default organization.

mushu org current

mushu org delete

Delete an organization (owner only).

mushu org delete <org_id>

Arguments

Name	Description	Required
`org_id`	Organization ID	Yes

Options

Flag	Description
`--force, -f`	Skip confirmation

mushu org members

Organization member management

mushu org members

mushu org invites

Organization invite management

mushu org invites

app commands

App management

mushu app create

Create a new app.

mushu app create <name>

Arguments

Name	Description	Required
`name`	App name	Yes

Options

Flag	Description
`--bundle-id, -b`	iOS bundle ID (e.g., com.company.app)*
`--org, -o`	Organization ID
`--android`	Android package name

mushu app list

List apps in an organization.

mushu app list

Options

Flag	Description
`--org, -o`	Organization ID

mushu app show

Show app details.

mushu app show [app_id]

Arguments

Name	Description	Required
`app_id`	App ID	No

mushu app use

Set default app for commands.

mushu app use <app_id>

Arguments

Name	Description	Required
`app_id`	App ID to set as default	Yes

mushu app current

Show current default app.

mushu app current

mushu app delete

Delete an app (admin only).

mushu app delete [app_id]

Arguments

Name	Description	Required
`app_id`	App ID	No

Options

Flag	Description
`--force, -f`	Skip confirmation

api-key commands

API key management

mushu api-key create

Create a new API key for an app. The full key is only shown once - save it immediately.

mushu api-key create <name>

Arguments

Name	Description	Required
`name`	Key name (e.g., 'production-backend')	Yes

Options

Flag	Description
`--app, -a`	App ID
`--scope, -s`	Scope: read, write, or admin
`--expires`	Days until expiry (default: never)

mushu api-key list

List API keys for an app.

mushu api-key list

Options

Flag	Description
`--app, -a`	App ID

mushu api-key show

Show API key details.

mushu api-key show <key_id>

Arguments

Name	Description	Required
`key_id`	API key ID	Yes

Options

Flag	Description
`--app, -a`	App ID

mushu api-key delete

Revoke an API key. The key will stop working immediately.

mushu api-key delete <key_id>

Arguments

Name	Description	Required
`key_id`	API key ID to revoke	Yes

Options

Flag	Description
`--app, -a`	App ID
`--force, -f`	Skip confirmation

tenant commands

Tenant management commands

mushu tenant create

Create a new notification tenant for an organization.

mushu tenant create

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)
`--bundle-id, -b`	iOS app bundle ID*
`--team-id, -t`	Apple Developer Team ID*
`--key-id, -k`	APNs Key ID*
`--key-file, -f`	Path to APNs .p8 key file*
`--sandbox`	Use sandbox APNs

mushu tenant list

List tenants for an organization.

mushu tenant list

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)

mushu tenant delete

Delete a tenant.

mushu tenant delete <tenant_id>

Arguments

Name	Description	Required
`tenant_id`	Tenant ID to delete	Yes

Options

Flag	Description
`--yes, -y`	Skip confirmation

mushu tenant use

Set default tenant.

mushu tenant use <tenant_id>

Arguments

Name	Description	Required
`tenant_id`	Tenant ID to set as default	Yes

mushu tenant api-key

Create an API key for a tenant.

mushu tenant api-key [tenant_id]

Arguments

Name	Description	Required
`tenant_id`	Tenant ID (uses default if not specified)	No

Options

Flag	Description
`--name, -n`	Key name

pay commands

Payment tenant management commands

mushu pay create

Create a new pay tenant for an organization.

mushu pay create

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)
`--name, -n`	Tenant name*
`--stripe-key, -k`	Stripe secret key*
`--webhook-secret, -w`	Stripe webhook secret

mushu pay list

List pay tenants for an organization.

mushu pay list

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)

mushu pay use

Set default pay tenant.

mushu pay use <tenant_id>

Arguments

Name	Description	Required
`tenant_id`	Pay tenant ID to set as default	Yes

mushu pay products

List products for a pay tenant.

mushu pay products [tenant_id]

Arguments

Name	Description	Required
`tenant_id`	Pay tenant ID (uses default if not specified)	No

mushu pay add-product

Add a product (one-time credit pack).

mushu pay add-product

Options

Flag	Description
`--tenant, -t`	Pay tenant ID (uses default if not specified)
`--name, -n`	Product name*
`--price, -p`	Price in cents (1000 = $10)*
`--credits, -c`	Credits to grant*

mushu pay balance

Check credit balance for a customer.

mushu pay balance

Options

Flag	Description
`--tenant, -t`	Pay tenant ID (uses default if not specified)
`--customer, -c`	Customer ID (uses current org if not specified)

mushu pay transactions

List transactions for a customer.

mushu pay transactions

Options

Flag	Description
`--tenant, -t`	Pay tenant ID (uses default if not specified)
`--customer, -c`	Customer ID (uses current org if not specified)
`--limit, -l`	Number of transactions to show

mushu pay auto-refill

Configure auto-refill for a customer.

mushu pay auto-refill

Options

Flag	Description
`--tenant, -t`	Pay tenant ID (uses default if not specified)
`--customer, -c`	Customer ID (uses current org if not specified)
`--enable`	Enable or disable auto-refill
`--product, -p`	Product to purchase for auto-refill
`--threshold`	Balance threshold to trigger auto-refill

mushu pay api-key

Create an API key for a pay tenant.

mushu pay api-key [tenant_id]

Arguments

Name	Description	Required
`tenant_id`	Pay tenant ID (uses default if not specified)	No

Options

Flag	Description
`--name, -n`	Key name

media commands

Media management commands

mushu media upload

Upload an image or video file.

mushu media upload <file_path>

Arguments

Name	Description	Required
`file_path`	Path to image or video file	Yes

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)
`--tenant, -t`	Tenant ID (optional, for tenant-specific media)

mushu media list

List media items for an organization.

mushu media list

Options

Flag	Description
`--org, -o`	Organization ID (uses default if not specified)
`--tenant, -t`	Filter by tenant ID
`--type`	Filter by type (image, video)

mushu media get

Get details for a media item.

mushu media get <media_id>

Arguments

Name	Description	Required
`media_id`	Media ID	Yes

mushu media delete

Delete a media item.

mushu media delete <media_id>

Arguments

Name	Description	Required
`media_id`	Media ID	Yes

Options

Flag	Description
`--force, -f`	Skip confirmation

mushu media url

Get download URL for a media item.

mushu media url <media_id>

Arguments

Name	Description	Required
`media_id`	Media ID	Yes

Options

Flag	Description
`--variant, -v`	Image variant (original, thumbnail, small, medium, large)

device commands

Device management commands

mushu device register

mushu device register

Options

Flag	Description
`--user, -u`	User ID*
`--token`	APNs device token*
`--platform, -p`	Platform (ios/watchos)
`--tenant, -t`	Tenant ID
`--version, -v`	App version
`--api-key, -k`	Tenant API key

mushu device list

List devices for a user.

mushu device list

Options

Flag	Description
`--user, -u`	User ID*
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

mushu device unregister

Unregister a device token.

mushu device unregister

Options

Flag	Description
`--user, -u`	User ID*
`--token`	Device token*
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

push commands

Push notification commands

mushu push send

Send a push notification to a user.

mushu push send

Options

Flag	Description
`--user, -u`	Target user ID*
`--title`	Notification title
`--body, -b`	Notification body
`--tenant, -t`	Tenant ID
`--badge`	Badge count
`--sound`	Sound name
`--payload, -p`	Custom JSON payload
`--silent, -s`	Silent/background push
`--api-key, -k`	Tenant API key

mushu push bulk

Send push to multiple users.

mushu push bulk

Options

Flag	Description
`--users`	Comma-separated user IDs*
`--title`	Notification title
`--body, -b`	Notification body
`--tenant, -t`	Tenant ID
`--badge`	Badge count
`--silent, -s`	Silent/background push
`--api-key, -k`	Tenant API key

email commands

Email notification commands

mushu email add-domain

Add a domain for email sending.

mushu email add-domain <domain>

Arguments

Name	Description	Required
`domain`	Domain to add (e.g., acme.com)	Yes

Options

Flag	Description
`--tenant, -t`	Tenant ID
`--from-name`	Default sender name

mushu email verify-domain

Check domain verification status.

mushu email verify-domain <domain>

Arguments

Name	Description	Required
`domain`	Domain to verify	Yes

Options

Flag	Description
`--tenant, -t`	Tenant ID

mushu email get-domain

Get domain details including DNS records.

mushu email get-domain <domain>

Arguments

Name	Description	Required
`domain`	Domain to get details for	Yes

Options

Flag	Description
`--tenant, -t`	Tenant ID

mushu email delete-domain

Remove a domain from the tenant.

mushu email delete-domain <domain>

Arguments

Name	Description	Required
`domain`	Domain to delete	Yes

Options

Flag	Description
`--tenant, -t`	Tenant ID
`--force, -f`	Skip confirmation

mushu email add-contact

mushu email add-contact

Options

Flag	Description
`--user, -u`	User ID*
`--email, -e`	Email address*
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

mushu email list-contacts

List email contacts.

mushu email list-contacts

Options

Flag	Description
`--user, -u`	Filter by user ID
`--email, -e`	Filter by email
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

mushu email unsubscribe

Unsubscribe an email contact.

mushu email unsubscribe <email_address>

Arguments

Name	Description	Required
`email_address`	Email to unsubscribe	Yes

Options

Flag	Description
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

mushu email send

Send an email notification to a user.

mushu email send

Options

Flag	Description
`--user, -u`	Target user ID*
`--subject, -s`	Email subject*
`--html`	HTML body (or use --file)
`--file, -f`	HTML file to send
`--text`	Plain text body
`--from`	Sender email (must be @verified-domain)
`--tenant, -t`	Tenant ID
`--api-key, -k`	Tenant API key

health commands

Health metrics and longevity commands

mushu health ingest

Ingest health metrics for a user. Examples: mushu health ingest user_123 -m vo2_max:52.3:mL/kg/min -m hrv_rmssd:45:ms --key sk_... mushu health ingest user_123 -m resting_heart_rate:58:bpm --on 2026-04-01 --key sk_...

mushu health ingest <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--metric, -m`	Metric in format name:value[:unit] e.g. vo2_max:52.3:mL/kg/min*
`--on`	Date YYYY-MM-DD (default: today)
`--app, -a`	App ID
`--key, -k`	API key*

mushu health get

Get health metrics for a user. Examples: mushu health get user_123 --key sk_... mushu health get user_123 --days 90 -m vo2_max -m hrv_rmssd --key sk_...

mushu health get <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--days, -d`	Number of days back (default: 30)
`--metric, -m`	Filter to specific metrics
`--app, -a`	App ID
`--key, -k`	API key*

mushu health longevity

Get longevity score for a user. Composite score (0-100) based on VO2 max, HRV, resting heart rate, sleep, steps, SpO2, and respiratory rate. Example: mushu health longevity user_123 --key sk_...

mushu health longevity <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--app, -a`	App ID
`--key, -k`	API key*

mushu health nutrition-week

Get 7-day nutrition summary for a user. Example: mushu health nutrition-week user_123 --date 2026-04-29 --key sk_...

mushu health nutrition-week <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--date, -d`	Anchor date YYYY-MM-DD (returns this day + 6 preceding)*
`--app, -a`	App ID
`--key, -k`	API key*

mushu health nutrition-tdee

Get Mifflin-St Jeor TDEE breakdown for a user. Returns BMR, TDEE, target calories, activity factor, and protein goal. Requires weight, height, and age to be set in nutrition preferences. Example: mushu health nutrition-tdee user_123 --key sk_...

mushu health nutrition-tdee <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--app, -a`	App ID
`--key, -k`	API key*

mushu health profile

Get or set health profile for a user. With no options, shows the current profile. With options, updates the profile. Examples: mushu health profile user_123 --key sk_... mushu health profile user_123 --dob 1989-01-01 --sex male --height-m 1.78 --key sk_...

mushu health profile <user_id>

Arguments

Name	Description	Required
`user_id`	User ID	Yes

Options

Flag	Description
`--dob`	Date of birth YYYY-MM-DD
`--sex`	Biological sex (male/female)
`--height-m`	Height in meters
`--app, -a`	App ID
`--key, -k`	API key*

mushu health redirect-uri

Manage Withings OAuth allowed redirect URIs

mushu health redirect-uri

agents commands

AI agent runs and BYOK configuration

mushu agents run

Submit an agent run and optionally wait for the result.

mushu agents run

Options

Flag	Description
`--user, -u`	User ID*
`--media, -m`	mushu-media R2 URL*
`--workflow, -w`	Workflow name
`--api-key, -k`	Tenant API key
`--poll`	Poll for result (max 45s)

mushu agents status

Check the status of an agent run.

mushu agents status

Options

Flag	Description
`--job-id, -j`	Job ID*
`--api-key, -k`	Tenant API key

mushu agents conversation-create

Create a new multi-turn conversation. Prints the conv_id.

mushu agents conversation-create

Options

Flag	Description
`--user, -u`	User ID*
`--workflow, -w`	Workflow name (e.g. meal-plan)
`--api-key, -k`	Tenant API key

mushu agents conversation-send

Send a message to a conversation and optionally wait for the assistant reply.

mushu agents conversation-send

Options

Flag	Description
`--conv-id, -c`	Conversation ID*
`--message, -m`	Message content*
`--api-key, -k`	Tenant API key
`--poll`	Poll for reply (max 60s)

mushu agents conversation-poll

Poll for the result of a sent message.

mushu agents conversation-poll

Options

Flag	Description
`--conv-id, -c`	Conversation ID*
`--pending-id, -p`	Pending ID from send*
`--api-key, -k`	Tenant API key

mushu agents conversation-list

List conversations for a user.

mushu agents conversation-list

Options

Flag	Description
`--user, -u`	User ID*
`--api-key, -k`	Tenant API key

mushu agents tool-hook-set

mushu agents tool-hook-set

Options

Flag	Description
`--app, -a`	App ID*
`--name, -n`	Tool name (used by LLM)*
`--url`	HTTPS URL the worker will POST to*
`--description, -d`	Tool description shown to LLM*
`--schema, -s`	Path to JSON file with parameters_schema
`--auth-header`	Authorization header value sent with each hook call
`--token, -t`	Bearer token (overrides stored auth)

mushu agents tool-hook-list

List all registered HTTP tool hooks for an app.

mushu agents tool-hook-list

Options

Flag	Description
`--app, -a`	App ID*
`--token, -t`	Bearer token (overrides stored auth)

mushu agents tool-hook-delete

Delete a registered tool hook from an app.

mushu agents tool-hook-delete

Options

Flag	Description
`--app, -a`	App ID*
`--name, -n`	Tool name to delete*
`--token, -t`	Bearer token (overrides stored auth)

mushu agents set-ambient-workflow

Set the ambient workflow for an app (used for SMS/WhatsApp inbound messages).

mushu agents set-ambient-workflow

Options

Flag	Description
`--app, -a`	App ID*
`--workflow, -w`	Workflow name to use for ambient (SMS/WhatsApp) conversations*
`--token, -t`	Bearer token (overrides stored auth)

mushu agents chatgpt-status

Check ChatGPT Plus connection status for this tenant. Shows whether the tenant's ChatGPT Plus subscription is connected, expired, or not yet set up. Connecting requires the iOS app.

mushu agents chatgpt-status

Options

Flag	Description
`--api-key, -k`	Tenant API key

messaging commands

Two-way messaging (SMS + WhatsApp) via Twilio channels

mushu messaging send

Send an outbound message via the given channel.

mushu messaging send

Options

Flag	Description
`--to, -t`	Recipient identifier (E.164 phone for SMS, 'whatsapp:+...' for WhatsApp)*
`--body, -b`	Message body*
`--channel, -c`	Channel ID (twilio_sms \| twilio_whatsapp_sandbox)
`--media, -m`	Optional media URL (MMS / WhatsApp media)
`--api-key, -k`	Tenant API key

mushu messaging health

Check the messaging service and list registered channels.

mushu messaging health

Environment Variables

The CLI can also be configured using environment variables:

Variable	Description
`MUSHU_AUTH_URL`	Override the auth API URL
`MUSHU_NOTIFY_URL`	Override the notify API URL

Configuration File

The CLI stores configuration in ~/.mushu/config.json. This includes API URLs and your default tenant.

Tokens are stored separately in ~/.mushu/tokens.json. These are refreshed automatically when needed.