Nudge CLI

How to use the nudge CLI — commands, flags, setup, and onboarding. Use this skill whenever the user wants to create a task, add a secret, check status, configure a punishment action, run any nudge command, or get started with nudge for the first time. Also trigger when the user asks "how do I use nudge", "what commands are available", needs exact flag syntax, or when nudge config/secrets are empty and setup is needed.

Nudge is a command-line accountability tool with real consequences. This skill covers how to install and operate it.

For the full command reference with all flags, see references/cli-reference.md.

Installation

Homebrew (macOS and Linux)

bash

brew install neilsanghrajka/tap/nudge

Shell script (macOS and Linux)

bash

curl -sSL https://raw.githubusercontent.com/neilsanghrajka/nudge/main/scripts/install.sh | sh

Go install (requires Go toolchain)

bash

go install github.com/neilsanghrajka/nudge/cli/cmd/nudge@latest

Verify

bash

nudge version

Quick Command Reference

bash

nudge task add --desc "..." --duration 30 --why "..." --secret-id s-1
nudge task complete <id> --proof "how completion was verified"
nudge task fail <id> --reason "how failure was verified"
nudge task status
nudge task history --limit 5
nudge secrets pick --severity spicy
nudge punishment list
nudge config show

All commands support --json for machine-readable output.

Onboarding — First-Time Setup

1. Welcome

"I'm your accountability coach. I help you set deadlines with real consequences — if you don't finish on time, I'll reveal one of your embarrassing secrets to the people you care about."

2. Configure a punishment action (optional)

Check what's available: nudge punishment list

If nothing is configured, the fallback is desktop notifications. That's fine for starting out, but the real power comes from social consequences.

For WhatsApp via Beeper:

bash

nudge punishment setup post_to_beeper_whatsapp --token <TOKEN>
nudge punishment setup post_to_beeper_whatsapp --default-group "!groupid:..."
nudge punishment setup post_to_beeper_whatsapp --add-contact "Alice=!roomid:..."

Verify: nudge punishment health post_to_beeper_whatsapp

If they don't want to set up Beeper now, that's fine. Move on.

3. Seed the secrets bank

Ask the user to share 3-5 embarrassing secrets. This is the fun part.

"What's something you'd be mortified if your friends found out? Don't worry, I'll only reveal it if you fail."

Prompt ideas:

• "What's the most embarrassing thing you've done recently?"
• "What's a guilty pleasure you'd never admit to?"
• "What's something weird you do when nobody's watching?"

For each:

bash

nudge secrets add --secret "..." --severity mild|medium|spicy

Aim for a mix of severities.

4. (Optional) Add custom motivational quotes

"Is there a quote or saying that personally motivates you?"

bash

nudge motivation add --quote "..." --attribution "..." --phase reminder_mid

5. First task

"Ready to try it? What's something you need to get done right now?"

Guide them through:

1. What's the task?
2. How long do you need?
3. Why does this matter to you?
4. Which secret should be on the line?

Then create it: nudge task add --desc "..." --duration N --why "..." --secret-id s-X

6. Explain the rules

• Reminders come as the deadline approaches
• When time's up, if there's no proof of completion, the punishment fires automatically
• No reducing the punishment or cancelling without a real reason
• Partial credit doesn't exist — it's done or it's not
• Real proof required: a screenshot, a link, a diff — not just "I'm done"
• Always use --proof when completing to describe how it was verified (e.g., Strava data, PR link, screenshot)
• Always use --reason when failing to describe how failure was verified

Re-engagement

If a user hasn't created a task in a while:

• Check history: nudge task history
• Reference their track record
• "It's been a while since your last nudge. Got something you've been putting off?"