CLI

The todoke CLI lets you manage apps and API keys and send notifications from your terminal.

Installation

Note

@todoke/cli is not yet published to npm. Build it from the repository to use it.

# after cloning the todoke monorepo
bun install
cd apps/cli
bun run build

Building produces apps/cli/dist/index.js (mapped to todoke via the bin field in package.json). Run it in one of the following ways.

# run directly
node apps/cli/dist/index.js <command>

# or run bun link in apps/cli and invoke it globally as `todoke`
cd apps/cli
bun link
todoke <command>

The examples below use the todoke <command> form.

Login

todoke login --api-key pk_xxxxxxxxxxxxxxxx
# ✔ Logged in. Saved configuration to /Users/you/.todoke.json.

• --api-key <key>: Required. The API key issued in the dashboard.
• --api-url <url>: Optional. Defaults to https://api.todoke.dev.

Caution

todoke login requires an API key with the full scope. The connection check performed at login calls GET /api/v1/apps, which requires the full scope for API key authentication, so with a subscribe_only / notify scope key todoke login itself fails with “このAPIキーのスコープではログインできません。full スコープのAPIキーをダッシュボードで発行して使用してください。” (You cannot log in with this API key’s scope. Issue an API key with the full scope in the dashboard; 403 INSUFFICIENT_SCOPE) and no configuration is saved. For details on scopes, see API keys.

At login, the CLI calls GET /api/v1/apps internally to verify that the API key is valid. If authentication fails, the following is shown and no configuration is saved.

todoke login --api-key pk_invalid
# ✖ Authentication failed: <error message from the API>

The configuration file is saved to ~/.todoke.json (under os.homedir()) with permission 0600. Because apiKey and apiUrl are written as plaintext JSON, handle the file with care.

todoke logout
# Logged out.

Running logout while not logged in prints Not logged in. (shown in gray).

Caution

An API key is bound to exactly one app. When you access the API with API key authentication, the server restricts operations to only the app that issued the key (limitToAppId). As a result, todoke apps list shows only the single app the logged-in key belongs to, and apps delete / keys list / keys add / keys rm / apps stats can only be run against that same app. Use the dashboard to create new apps and to manage multiple apps across the board (app creation POST /api/v1/apps accepts session authentication only, so the CLI has no app-creation command).

Command reference

todoke login

Option	Required	Description
--api-key <key>	Required	API key (a string starting with pk_)
--api-url <url>	Optional	API URL (default: https://api.todoke.dev)

See the “Login” section above.

todoke logout

Deletes the saved credentials (~/.todoke.json).

todoke logout
# Logged out.

todoke apps list

Shows the app the logged-in key belongs to (no arguments).

todoke apps list
#
# Apps (1)
#
#   my-app  3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f

If there are no apps, No apps. (shown in gray) is printed.

todoke apps stats <app-id>

Shows an app’s statistics (active subscribers, total sends, failures, and sends this month).

todoke apps stats 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f
#
#   Active subscribers: 42
#   Total sends:        1234
#   Failures:           3
#   Sends this month:   567

todoke apps delete <app-id>

Deletes an app.

todoke apps delete 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f
# ✔ Deleted.

Danger

Deleting an app cascades to delete all of its API keys, subscriptions, statistics, and send logs, and cannot be undone.

todoke keys list <app-id>

Shows the list of API keys tied to an app (scope and last-used time).

todoke keys list 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f
#
# API keys (1)
#
#   backend-key  notify  Last used: 2026/7/2 10:00:00
#     8e1c2d3f-...

If there are no keys, No API keys. (shown in gray) is printed.

todoke keys add <app-id>

Creates an API key.

Option	Required	Description
-n, --name <name>	Required	Key name
-s, --scope <scope>	Optional	Scope (subscribe_only / notify / full). Defaults to notify

todoke keys add 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f -n backend-key -s notify
# ✔ Created: backend-key (notify)
#
#   API key: pk_a1b2c3d4e5f6...
#   * This key is shown only once. Be sure to copy it.

Caution

An API key is shown only once, at creation time. The displayed value is not stored and is included only in the response, so be sure to copy it on the spot.

todoke keys rm <app-id> <key-id>

Deletes an API key.

todoke keys rm 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f 8e1c2d3f-0000-0000-0000-000000000000
# ✔ Deleted.

todoke notify <app-id>

Sends a notification.

Option	Required	Description
-t, --title <title>	Required	Notification title
-b, --body <body>	Required	Notification body
-u, --url <url>	Optional	Destination URL on click (https:// only)
-e, --endpoint <endpoint>	Optional	Target a specific subscriber’s endpoint

See the “Sending notifications” section below for details.

Sending notifications

todoke notify 3f29a1d2-4b7d-4a91-9c3e-1f2b3a4d5e6f -t "Announcement" -b "You have a new message"
# ✔ Notification sent: "Announcement"

Use -u/--url to set the destination when the notification is clicked, and -e/--endpoint to send only to a specific subscriber.

Note

The <app-id> argument of the notify command is not referenced in the current implementation. The target app is determined not by this argument but by the app tied to the logged-in API key. To send to a different app, log in again with that app’s full scope key (since the CLI’s login requires the full scope).

Behavior on errors

If you run any command other than login / logout while not logged in, the following message is shown and the process exits with code 1.

todoke apps list
# Not logged in. Run `todoke login --api-key <key>`.

Other errors (invalid API key, insufficient scope, resource not found, etc.) display the API’s error message as-is, with exit code 1. For the full list of error codes, see Error codes and limits.