CLI commands

The ringly CLI has 8 subcommands. Run ringly help (or ringly --help) to see the list in your configured language.

ringly help

Prints the list of commands in the language set in pluginConfigs.ringly.options.language. Cyan box at the top, yellow warning that these commands run in the external terminal, list of the 7 subcommands with short descriptions.

ringly help
ringly --help
ringly -h

ringly init

Interactive installer (TUI). Performs everything from step 1: AUMID registration, Start Menu shortcut, initial settings.json write, and prints the step 2 command for you to paste into Claude Code.

ringly init

Flags

• --non-interactive — apply defaults, no TUI (useful in CI)
• --force — re-create shortcut and re-register AUMID even if already present

ringly config

Reconfigure interactively. Same TUI as init, minus the AUMID register. Arrow keys to navigate, space to toggle booleans, visual language picker. Writes atomically to settings.json with a timestamped backup.

ringly config

At the end, reminds you to run /reload-plugins in Claude Code so the active session picks up the new options.

ringly doctor

Diagnoses the local environment. Runs 9+ checks: Node version, platform, PowerShell, registered AUMID, valid settings.json, plugin installed, hooks registered, Start Menu shortcut, and test fire.

ringly doctor

Sample output:

✓ Node.js v22.14.0           (>= 20.0.0)
✓ Platform                   win32 x64
✓ PowerShell                 v5.1 detected
✓ AUMID registered           Claude.Code.CLI
✓ Claude Code settings       8 options set, en-US
✓ Plugin installed           ringly@0.6.0
✓ Hooks registered           5/5 active
✓ Start Menu shortcut        present
✓ Test fire                  toast displayed

9 passed · 0 warnings · 0 failed

ringly test

Fires a sample notification. Without flags, uses the Stop event and the configured language.

ringly test
ringly test --event Stop --lang en-US
ringly test --event Notification --title "Hello" --body "World"

Flags

• --event <Stop|Notification|StopFailure|SubagentStop|SessionStart> — which event to simulate
• --lang <auto|pt-BR|en-US> — force a language
• --title <string> — override the title
• --body <string> — override the body

Handy to debug whether something is blocking the toast (Focus Assist, wrong AUMID, etc.).

ringly update

Check npm and run the guided update.

ringly update              # interactive, visual box and confirmation
ringly update --check      # prints JSON {current, latest, hasUpdate, reachable, language, notes}
ringly update --yes        # skip prompt and install directly

--check is what the /ringly-update slash command consumes inside Claude Code. Detects EBUSY / EPERM / access is denied in the npm install stderr and swaps in a “close Claude Code and retry” message instead of dumping the raw error.

ringly uninstall

Removes the AUMID, Start Menu shortcut, and Ringly settings from settings.json (with automatic backup).

ringly uninstall
ringly uninstall --keep-config   # preserves pluginConfigs.ringly in settings.json

Does not uninstall the npm package itself (you’d do that with npm uninstall -g ringly) nor remove the plugin from Claude Code (use /plugin uninstall ringly).

ringly hook (internal)

Internal command used by the plugin dispatcher as a fallback when the Node module ringly/hook can’t be resolved. Accepts an event name as a positional argument and reads the JSON payload from stdin.

echo '{"hook_event_name":"Stop"}' | ringly hook Stop

Not documented in ringly help because it’s not meant for direct end-user use.