LystBot

Todo list CLI: manage shared lists from your terminal

LystBot is a todo list CLI for shared tasks and groceries that sync to the phone app. Run npm install -g lystbot, authenticate with lystbot login YOUR_API_KEY, then use lystbot add "Groceries" "Milk, Eggs, Bread" to save items from your terminal.

Command Operation Result
npx lystbot lists Read Show available lists
npx lystbot show "Groceries" Read Show list items
npx lystbot add "Groceries" "Milk, Eggs, Bread" Write Add three items
npx lystbot check "Groceries" "Milk" Write Check off milk

See the LystBot agent setup for the full reference. Related guides: REST and MCP interfaces for lists, grocery list automation examples.

Terminal showing LystBot CLI managing a shopping list

TL;DR

A shopping list command line workflow

When you remember an item while working, save it in the same terminal:

lystbot add "Groceries" "Milk, Eggs, Bread"

The phone app and CLI use the same lists, so the person shopping can see the addition.

Install and authenticate

Install

npm install -g lystbot

If you prefer running without a global install, use npx lystbot before each command.

Login

lystbot login YOUR_API_KEY

Copy the API key from Settings, then AI Agents in the app. Login stores it locally in ~/.lystbot/config.json.

Verify

lystbot lists

You should see your existing lists. If you're new to LystBot, download the app first and create a list there. Or create one from the terminal (we'll get to that).

LystBot app showing synced shopping lists LystBot list detail view with grocery items

Terminal list manager commands

Here's every command that matters, with real examples. No hypotheticals.

See all your lists

lystbot lists

Shows list names, item counts, and types. Quick overview without opening anything.

Show a specific list

lystbot show "Groceries"

Prints every item with its status (checked or not). Pipe it if you want:

lystbot show "Groceries" | grep milk

That's the kind of thing you can't do in a phone app. Filtering, searching, piping output into other tools. The command line grocery list becomes just another data stream you can work with.

Add items

lystbot add "Groceries" "Oat milk, Bananas, Sourdough bread"

Comma-separated, all in one command. Items sync to every device on the list immediately. Members of the shared list see the updated items in the phone app.

Push notification showing items added to shared grocery list via CLI

Check items off

lystbot check "Groceries" "Oat milk"

Name the item you intend to check, then read the list to verify its state.

Remove an item

lystbot remove "Groceries" "Bananas"

Read the list after removing an item to confirm the intended change.

Create a new list

lystbot create "BBQ Saturday" --type shopping

Types are shopping, todo, packing, and generic. Pick what fits.

Share a list

lystbot share "Groceries"

Generates a 6-character code. Send it to anyone. They join from the app with that code, no account creation hassle.

LystBot share code for joining a shared shopping list

Three terminal workflows

Commands are nice. Workflows are where a terminal list app becomes part of how you operate.

Morning routine: clear the decks

You're having coffee, terminal open, checking things before the day starts.

lystbot show "Groceries"

Yesterday you bought milk and eggs. Check them off:

lystbot check "Groceries" "Milk"
lystbot check "Groceries" "Eggs"

Glance at your todo list while you're at it:

lystbot show "Today"

Both lists are reviewed and updated in your terminal session.

Cooking mode: shop and check

You're in the kitchen, laptop on the counter (we all do it). Recipe open in one tab, terminal in another.

lystbot show "Groceries"

Check off ingredients as you pull them from the bag:

lystbot check "Groceries" "Chicken breast"
lystbot check "Groceries" "Rice"
lystbot check "Groceries" "Onions"

Realize you forgot garlic:

lystbot add "Groceries" "Garlic"

Your partner is still at the store? They see "Garlic" pop up on their phone. That's real-time shared list management from the terminal.

Meal prep: batch create

Sunday evening, planning meals for the week.

lystbot create "Week 14 Groceries" --type shopping
lystbot add "Week 14 Groceries" "Chicken thighs 1kg, Broccoli 2x, Sweet potatoes, Greek yogurt, Quinoa, Lemons, Garlic, Ginger, Soy sauce"

Two commands create the list and add nine items. Check their names and quantities in the phone app before shopping.

Ready to try it? Install LystBot CLI and manage your shopping lists from the terminal:

npm install -g lystbot

The CLI docs have the full command reference. Check the saved key and read a list before making a change.

Pipe-friendly by design

The CLI outputs clean text you can pipe, grep, and script with. Some examples:

Read structured items from one list:

npx lystbot show "Groceries" --json | jq '.items'

Export a list to a file:

lystbot show "Groceries" > groceries.txt

Add items from a file:

cat weekly-staples.txt | xargs -I {} lystbot add "Groceries" "{}"

If you've ever tried to export or script anything with a regular grocery app, you know this is unusual. Most list apps treat your data like it's theirs. LystBot treats your lists as data you own and can move however you want.

CLI vs. phone app: when to use which

I don't think the CLI replaces the phone app. They're for different moments.

Use the CLI when:

Use the phone app when:

The whole point is that both interfaces hit the same backend. Add something from the CLI, it's on the phone. Check something on the phone and the CLI reads the updated checked state. One list, multiple ways in.

Beyond the CLI: API and MCP

The CLI is one of three ways to manage lists from the terminal. LystBot also has a REST API for building automations (cron jobs, Slack bots, Home Assistant triggers) and an MCP server that lets AI assistants like Claude manage your lists in natural language.

All three talk to the same backend. Pick whichever fits the task:

If you're curious about what else you can build, we covered 4 real API automations and 10 MCP server use cases in separate posts.

Get started

LystBot is free during launch, with no account needed.

  1. Install the CLI: npm install -g lystbot (npm package)
  2. Login: lystbot login YOUR_API_KEY
  3. Add your first item: lystbot add "Groceries" "Coffee"

See it appear on your phone. That moment when a terminal command updates your shared shopping list in real time, that's when it clicks.

Full docs: lystbot.com/docs/cli

FAQ

Do I need a global install?

No. Use npx lystbot before a command, such as npx lystbot lists. A global install with npm install -g lystbot lets you use lystbot directly.

Does login open a browser?

The documented login uses an API key: npx lystbot login YOUR_API_KEY. Copy the key from Settings, then AI Agents; it is stored in ~/.lystbot/config.json.

How do I export structured items?

Use npx lystbot show "Groceries" --json | jq '.items' to read the list items as JSON. Check the returned list before using that output in a script.