The short answer
Download one file with curl and log in once with your Culinary Card account. `whoami` shows your credit balance, `list` and `view` read your collection, and `create` turns pasted text, a file or a URL into a structured recipe card, using the same AI and the same credits as the web app. Every command takes a --json flag, so it is easy to script and to hand to an AI agent.
Step-by-step
- 1
Download it and log in once
The CLI is a single file with no dependencies. Download it with curl; there is no repo to clone and nothing to npm install. Log in with your email and password, or, if you sign in with Google, generate a one-time code in the app (Profile settings → Preferences → Command line access) and use connect. Your session is stored locally (chmod 600) and refreshes itself automatically.
curl -fsSL https://www.culinarycard.app/cli.js -o cli.js node cli.js login [email protected] # email + password accounts node cli.js connect ABCD-2345 # Google sign-in accounts (one-time code) - 2
Check your account and browse your collection
whoami shows your email, credit balance, and recipe count. list takes search and limit flags, where --search matches recipe titles. view prints a full recipe, ingredients and steps and notes, formatted for the terminal.
node cli.js whoami node cli.js list --search "chicken" --limit 10 node cli.js view <recipe-id> - 3
Create recipes without opening a browser
Pipe in raw text, point at a file, or hand it a URL. The same AI that powers the web app turns it into a recipe card and saves it to your collection. Text costs 1 credit and URL imports cost 2, the same as the web app.
node cli.js create --text "Grandma's lemonade: juice of 6 lemons, 1 cup sugar, 6 cups water..." node cli.js create --file ./recipe-notes.txt node cli.js create --url https://example.com/best-focaccia - 4
Add --json and hand it to your agent
Every command emits machine-readable JSON with --json, exits non-zero on failure, and reports errors as JSON on stderr. So Claude Code, a ChatGPT tool, a cron job or any script can drive your recipe book without scraping HTML.
node cli.js list --json | jq '.recipes[].title' node cli.js create --url "$URL" --json > new-recipe.json - 5
Or skip the CLI and hit the API directly
The CLI is a thin client over a stable JSON API. If you're building your own integration or agent tool, POST /api/cli/login gets you a token and the /api/cli/recipes endpoints do the rest. The rate limits are set with scripts in mind.
curl -s -X POST https://culinary-card-production.up.railway.app/api/cli/login \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"..."}'
Common mistakes to avoid
- ✕
Letting your recipes live only in AI chat threads
If you cook with ChatGPT or Claude, the recipes you refine together vanish into scrollback. One `create --text` call and the final version is saved, searchable, and rendered as a proper card.
- ✕
Scraping your own data out of a web UI
Browser automation against a recipe site breaks every time the page layout changes. An agent that calls a JSON API keeps working week after week.
- ✕
Handing an agent unlimited spend
Recipe creation costs the same credits as the web app and is rate-limited server-side, so a runaway loop can't drain your account. Reads are effectively free and generously limited.
- ✕
Storing platform API keys in scripts
The CLI never sees or stores infrastructure keys. You log in with your own account, the token lives in a permission-restricted file in your home directory, and logging out revokes it.
Why Culinary Card works for this
The CLI calls the same import pipeline as the web app, so a recipe created from the terminal comes out identical to one pasted into the browser, and it lands in the same collection. Terminal users get a keyboard workflow, and agent builders get a documented JSON interface with real exit codes and server-side spending limits.
Frequently asked questions
Do I need to install anything?
Only Node 18 or newer. The CLI has no dependencies; it is a single script that uses the built-in fetch. Download it with `curl -fsSL https://www.culinarycard.app/cli.js -o cli.js` and run it with node. No repo access, no npm install.
I sign in with Google. How do I log in without a password?
Use connect instead of login. In the app, go to Profile settings → Preferences → Command line access and generate a one-time code, then run `node cli.js connect <code>`. The code is valid for 10 minutes and single-use; the CLI gets its own session that refreshes automatically.
Can AI agents like Claude Code use it?
Yes, it was designed for that. In practice you tell the agent the CLI exists, paste the help text once, and it composes commands from there. Predictable flags, structured errors and honest exit codes matter far more to an agent than readable output does.
Does CLI usage cost the same as the web app?
Yes. Creating a recipe from text costs 1 credit and importing from a URL costs 2, the same as the web app. Listing and viewing recipes is free. Rate limits are generous: 120 reads per minute and 20 recipe creations per hour.
Is it secure to let a script log in as me?
Your session token is stored in ~/.culinarycard.json with owner-only file permissions and refreshes automatically. Nothing else is stored. Run logout to delete it instantly, and login attempts are rate-limited server-side.
What can't the CLI do yet?
Editing, deleting, and image generation are web-app-only for now. If you need one of those from the CLI, say so through Feedback in the app.