@sharetodos/cli

Manage your sharetodos lists from the terminal. Add items, tick things off, invite collaborators — without leaving your editor.

npm install -g @sharetodos/cli

Requires Node.js 18+.

Quick start

todo login
todo add "buy milk" "call dentist"
todo list
todo done "milk"

That's it. Everything syncs instantly with the web app and any other platform (email, SMS) your list is shared on.

Commands

Auth

todo login                     # opens browser → authorize in sharetodos.com → done
todo login --no-browser        # paste an API key instead (SSH / headless)
todo login --key sk_live_...   # provide a key directly (CI / scripts)
todo logout                    # clear stored credentials

todo login opens sharetodos.com/cli-auth in your browser. Once you click Authorize, an API key is created and stored automatically — no copy-pasting required. The key appears in your developer settings so you can revoke it any time.

Lists

todo lists                  # show all your lists (★ marks the active default)
todo use [list-name]        # set or show the default list (like nvm use)
todo new "Barcelona Trip"   # create a new list

Items

todo add "buy milk" "call dentist"    # add to default list
todo add "buy milk" --list shopping   # add to a specific list
todo list                             # show open items
todo list --list shopping             # items in a specific list
todo done "buy milk"                  # mark done (fuzzy match)
todo done --all                       # mark everything done
todo undone "buy milk"                # unmark done
todo clear                            # archive all completed items
todo undo                             # reverse the last action

Collaboration

todo invite [email protected] --list shopping   # invite a collaborator
todo share                                      # print share URL + QR code

Updates

todo update   # update to the latest version

Developer commands

todo count                          # open item count — useful for shell prompts
todo search "dentist"               # fuzzy search across all lists
todo export --format md             # export to Markdown, JSON, or CSV
todo import tasks.txt               # bulk-add items from a file or stdin
todo move "buy milk" --to groceries # move an item to another list
todo config                         # show current config
todo completion zsh                 # generate shell completions

Flags available on most commands

| Flag | Description | |------|-------------| | --list <name> | Target a specific list instead of the default | | --json | Output raw JSON (pipe-friendly) |

Item syntax

The same shorthand works here as in the web compose bar and email:

| Syntax | Effect | |--------|--------| | #tag | Adds a tag | | @name | Assigns to a collaborator | | due:friday | Sets a due date | | ! | Marks as priority |

todo add "call dentist ! due:friday #health @jane"

Shell integrations

Pipe from clipboard (macOS):

pbpaste | todo add

Pipe from a file:

cat sprint-tasks.txt | todo add --list work

Shell prompt (item count):

# starship.toml
[custom.todo]
command = "todo count --json 2>/dev/null | node -pe 'JSON.parse(require(\"fs\").readFileSync(\"/dev/stdin\",\"utf8\")).count'"
when = "true"
symbol = "✓ "

JSON output for scripting:

todo list --json | jq '.items[] | select(.priority) | .text'

Shell completions:

# zsh — add to ~/.zshrc
eval "$(todo completion zsh)"

# bash — add to ~/.bashrc
eval "$(todo completion bash)"

# fish
todo completion fish | source

Links

• Web app — sharetodos.com
• Help docs — help.sharetodos.com
• npm — npmjs.com/package/@sharetodos/cli