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, confi...

Security Scan

The skill is internally coherent as a user guide for the 'nudge' CLI, but it includes high-risk install instructions (curl|sh from a third‑party repo) and runtime guidance that solicits and transmits highly sensitive personal secrets to external services — things the user should review before using.

Purpose & Capability

Name/description match the content: this is an instruction-only CLI guide for the 'nudge' tool and the included commands, onboarding, and punishment actions are consistent with that purpose. It legitimately shows how to configure external posting actions (e.g., Beeper/WhatsApp) and how to seed secrets used by the tool.

Instruction Scope

The instructions explicitly direct the agent/user to solicit 3–5 'embarrassing secrets' and configure actions that will transmit those secrets to external recipients (Beeper/WhatsApp). While this matches the product purpose, it means the skill instructs collection and transmission of highly sensitive personal data — a privacy risk. The SKILL.md also instructs passing tokens (e.g., --token) on the command line and using default data-dir (~/.nudge); these runtime steps are not declared in metadata and broaden the effective scope.

Install Mechanism

There is no formal install spec in the registry, but SKILL.md recommends installing via brew (third‑party tap), 'go install' from a GitHub repo, or running a remote install script with 'curl https://raw.githubusercontent.com/... | sh'. Piping a remote script to sh and using a personal Homebrew tap are higher-risk actions and should be treated with caution — the skill's metadata did not include an install artifact or checksum to verify.

Credentials

The published metadata requests no environment variables or credentials, which is consistent with a documentation-only skill. However, the runtime instructions show commands that accept tokens and target identifiers (e.g., --token, --default-group, --add-contact). Those credentials are necessary for punishment actions but are not declared in requires.env; users should be aware they will need to supply service tokens and that passing secrets on the command line can expose them via shell history.

Persistence & Privilege

The skill is user-invocable and not always-included; it requests no special platform privileges, doesn't modify other skills, and has no install-time persistence declared. Autonomous invocation is allowed (platform default) but unremarkable on its own.

What to consider before installing

This is a how-to for a CLI that intentionally collects and can publish sensitive, personal 'secrets' to third parties — that's the product, not a hidden behavior. Before installing or using it: 1) Do not run 'curl | sh' unless you have inspected the script and trust the upstream repo; prefer vetted packages or verify checksums. 2) Review the GitHub repo (neilsanghrajka/nudge) and Homebrew tap to confirm authorship and review install scripts. 3) Be cautious supplying tokens on the command line (they can end up in shell history); prefer storing credentials securely. 4) Understand legal/privacy/ethical consequences of sending private information to contacts or services; get consent where appropriate. 5) If you want this skill only as documentation (no installs), you can use the guidance without running installers. If you need a deeper analysis (e.g., review of the remote install script or the upstream repo contents), provide the install script or repo URL and I can examine it — that would raise confidence in the assessment.

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)

brew install neilsanghrajka/tap/nudge

Shell script (macOS and Linux)

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

Go install (requires Go toolchain)

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

Verify

nudge version

Quick Command Reference

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:

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:

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?"

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?"