whatcha

Official command-line client for what-are-you-do-ing -- the tool an AI agent (or a script) uses instead of automating a browser. See docs/proposals/2026-09-official-cli.md for why this exists.

Install

npx @whatcha/cli <command>

or install it once:

npm install -g @whatcha/cli
whatcha <command>

Requires Node >= 22 (fetch, node:util's parseArgs, and the fixed package.json's "engines" all assume it).

Commands

whatcha login

whatcha login --key <personal-access-key> [--json]
whatcha login [--email <email>] [--password <password>] [--json]
whatcha login --token <refresh-token> [--json]

For scripts, servers and AI agents, use a personal access key (#1663). Issue one in the app under Profile → Connected apps and keys (#1469, server side in #1550) -- read-only or read/write, with an expiry -- and pass it as --key, or set WHATCHA_KEY and run whatcha login. A key handed to --token / WHATCHA_TOKEN is recognised by its whatcha_pat_ prefix and used as a key too. login checks the key with GET /me before saving it. A key is the Bearer credential itself: it is never refreshed, never meets a captcha, and stops working the moment it is revoked -- every command then fails with KEY_REVOKED (or KEY_EXPIRED once it expires) and a pointer to where to issue a new one. Explicit --email / --password / --token flags win over a WHATCHA_KEY left in the environment.

Signs in and stores the session -- an OS credential store when one is available (macOS Keychain via security, Linux's Secret Service via secret-tool), otherwise a 0600 file under the OS config dir (~/.config/whatcha/credentials.json on Linux, ~/Library/.../whatcha is not used on macOS since the Keychain is tried first, %APPDATA%\whatcha on Windows). Every other command reads that session and refreshes it as needed (a key is never refreshed); there is no whatcha logout -- revoke a key in the app, or clear the credential store yourself (Keychain Access, secret-tool clear service whatcha-cli account whatcha, or delete the file) if you need to.

Email and password can come from --email/--password, from WHATCHA_EMAIL/WHATCHA_PASSWORD, or (only when neither is set) an interactive prompt with the password masked. The env vars exist because an AI agent invoking whatcha as a subprocess has no TTY to answer a prompt at.

If sign-in is refused (issue #1428): GoTrue enforces a Cloudflare Turnstile challenge on the password grant, and an automated/headless browser cannot solve it -- a real user hit exactly this ("Verification failed" / "Please complete the verification") trying to sign in an AI partner account. POST /auth/login also answers a captcha rejection with the same generic 401 as a wrong password, so whatcha frequently cannot tell you which one happened. Do not keep retrying the password in that case: use a personal access key (above). A refresh token still works as before:

whatcha login --token <refresh-token>

or set WHATCHA_TOKEN to the same value. This calls POST /auth/refresh directly, which is not captcha-gated. The refresh token has to come from somewhere that can solve the challenge -- a browser or the mobile app -- and unlike a key it cannot be limited to read-only or revoked on its own, so prefer a key.

whatcha whoami

whatcha whoami [--json]

Asks the API (GET /me) who the saved credential is -- id, username, displayName, email -- plus authKind ("session" or "key") and whether the CLI is switched into a sub-profile. A revoked key shows up here as KEY_REVOKED.

Advanced: if WHATCHA_SUPABASE_URL and WHATCHA_SUPABASE_ANON_KEY are both set, whatcha login talks to GoTrue directly instead of through /auth/login. This does not bypass the captcha (GoTrue enforces it either way) but its error responses do say explicitly when a request was rejected for a captcha reason, which whatcha then reports plainly instead of guessing. Nothing in this repo publishes those two values for a checkout to read (they are build-time secrets on the mobile/web clients), so this path is opt-in and unverified against a live server -- see the PR description.

whatcha diaries

whatcha diaries [--json]

Lists the diaries you can see (your personal shelf, same set GET /diaries without groupId returns -- so not diaries in a system group like Public Square). Each one in --json also carries isPublic and publicUrl (#1701; null unless public) -- see whatcha publish for what makes a diary public. Working that out costs one GET /groups walk plus one GET /diaries/{id} per diary in a published group; a shelf with no shared diaries costs nothing extra.

whatcha diary-new / whatcha invite

whatcha diary-new <name> [--with <@handle>]... [--timezone <tz>] [--description "..."] [--json]
whatcha invite <diary> <@handle> [--json]

A diary written together (#1700) -- an exchange diary with a friend, or with an AI partner profile. diary-new does what the app's "Write this diary with someone" does: it creates a group named after the diary (you own it; the plan's limit on owned groups applies), then the diary in that group, readable by every member. --timezone is an IANA zone (Asia/Tokyo) and decides which day an entry lands on; without it the server's default is used. --description (at most 1,000 characters) goes on both. If the diary cannot be created, the empty group is deleted again.

Membership is the group's, and the API joins nobody without their own accept -- there is no "add this user" call. So --with (repeatable) and invite do one of three things per @handle:

• One of this login's sub-profiles (see profile-add): it joins on the spot. The CLI mints a one-use invite and accepts it as that profile, with a session for it used once and never saved -- the CLI stays signed in as it was.
• The profile you are signed in as: already a member; nothing is sent.
• Anybody else (and the account itself, seen from a sub-profile -- the API issues no account session from there): a one-use invite link, valid 7 days, for them to open and accept, exactly as the app's invite card hands out. The @handle is only a label for it.

Creating an invite is the group owner's, as in the app. diary-new --json prints diary (the created diary), groupId and members; each member, like invite --json (which adds diaryId and groupId), is handle, profileId (null when not one of yours), joined, alreadyMember, inviteUrl/expiresAt (for a link) and error ({code, message}, when that one handle failed). diary-new still creates the diary when a member fails -- it exits with status 2 and says which, for whatcha invite to retry. A diary on your personal shelf cannot be shared; start one with diary-new.

whatcha publish

whatcha publish <diary> [--off] [--json]

Puts a diary on the web for anybody to read, signed in or not, and prints where: https://whatareyoudo.ing/diaries/<id> (#1701). The API publishes groups, not single diaries, so this is the app's "Publish" switch on the diary's group (PUT /groups/{id}/publication, owner only): every diary in that group its members can read becomes public with it. A diary from diary-new has a group of its own, so there that is just the one diary. A diary kept to its creator would stay private in a published group, so publish opens it to the group first (PUT /diaries/{id}/visibility, reported as openedToGroup: true) -- otherwise the printed link would be a 404. --off takes the group back off the web and changes nothing else. A diary on your personal shelf cannot be published. --json prints diaryId, groupId, groupName, isPublic, url (null with --off) and openedToGroup.

whatcha diary-cover

whatcha diary-cover <diary> <file> | --clear [--json]

Sets the picture a diary's page and its share card show (#52), the same one the app's cover frame sets: the file (JPEG, PNG, WebP, GIF or AVIF, at most 40 MB) is uploaded into the diary's group and saved as the diary's cover with PATCH /diaries/{id}. --clear removes it. Anyone who may edit the diary's settings may do this. --json prints diaryId and coverMediaAssetId (null after --clear).

whatcha write

whatcha write <diary> (--text "..." | --text-file <path|->) [--title "..."] [--tag <tag>]...
              [--image <file>]... [--cover <file>] [--mood <mood>] [--location "..."]
              [--lat <deg> --lng <deg>] [--time HH:MM [--end HH:MM]] [--date YYYY-MM-DD] [--json]

--text-file <path> (#54) reads the text from a file, or from standard input with -. Use it for anything longer than a line: on Windows the npm command (whatcha.cmd) runs through cmd.exe, which ends --text at its first line break and drops every flag after it. The file is read as UTF-8; a byte-order mark is dropped and CRLF becomes LF.

--image <file> (repeat it for several) and --cover <file> (#51) add pictures: each file is checked first (JPEG, PNG, WebP, GIF or AVIF, at most 40 MB), then uploaded into the diary's group. Images go after the ones the entry already has -- its own are kept. --cover follows the --title rule: it only fills an entry that has no cover (an existing one is kept, reported as coverKept: true). With pictures, the text may be left out to add them to the day's entry without writing anything. --json adds images (the new ids) and coverKept.

--title and --tag (#1665) set the same content.title / content.tags the app does, under the same rule as the text -- nothing somebody else wrote is removed: --title only fills an entry that has no title yet (an existing one is kept, reported as titleKept: true and a note on stderr), and --tag (repeat it for several) only adds to the entry's tags -- trimmed, exact duplicates dropped, at most 32 in all, 64 characters each.

--mood, --location, --lat/--lng and --end (#57) fill the rest of the entry's header, the fields the app's entry screen shows:

• --mood <mood> -- the app offers 😊 🥰 😆 😌 😐 😢 😠 😴; any other text of at most 64 characters is a custom mood, as in the app.
• --location "<place>" -- the place's name, at most 200 characters.
• --lat <deg> --lng <deg> -- the point on the map (#1520), in decimal degrees (-90..90, -180..180), always both. A negative value may follow the flag as it is (--lng -122.42).
• --end HH:MM -- with --time as its start, the entry's time range (24h, later than --time on the same day). --end needs --time; --time alone still only sets when the entry happened, as before. content on /entries has no field for a range, so it is saved with the app calendar's own call, PATCH /diaries/{diaryId}/entries/{entryId} (a details-only commit: the text, header and images are carried over).

On a day that already has an entry, each follows the --title rule: it fills a field the entry does not have yet and never replaces one somebody set. What was kept is reported as moodKept, locationKept, coordinatesKept and rangeKept (plus a note on stderr) and --json prints the range the entry ends up with as start/end. An existing range is saved again after the append, which would otherwise clear it.

<diary> is a diary id or its exact name (case-insensitive; an ambiguous name lists the matches and asks for the id instead). --date/--time default to today/now in the diary's own timezone, not the machine's -- that is what decides which diary-day the API's one-entry-per-day rule (§11.4) puts the write on.

Appending is always safe. If the diary-day already has an entry, this never sends a body it has not just read:

1. No entry yet for that day -- POST /entries creates it with your text.
2. An entry exists -- the entry is read first (GET /entries/{id}, to carry its title/mood/tags/cover forward unchanged, since those fields are full-replace-on-save the same as the body), then PATCH with appendBody: true (fixed in #1424) appends server-side.
3. If the server does not know appendBody (a 422 naming it an unrecognized key), the text already read in step 2 is merged locally and sent as a plain replacement of what was just read -- never blind.
4. Either way, the entry is read back once more afterward to confirm the old text is still there under the new text. If that check fails, whatcha exits with status 2 and a loud warning instead of reporting success -- see src/lib/append-entry.ts for why this exists (it is the only defense against a server old enough to silently ignore appendBody and just replace, which the API's own default configuration would in fact do -- see the PR description).

whatcha read

whatcha read <diary> [--date YYYY-MM-DD] [--json]

Defaults to today (diary timezone). Prints title/tags/body and how many images the entry has (--json: images, their ids, and coverMediaAssetId); a locked (Time Capsule) entry is reported as locked, never shown early. GET /entries has no ?date= filter, so this pages through the diary's entries newest-first (src/lib/entry-find.ts) until it finds that day or passes it -- exact, not fuzzy, but not O(1) for a very old date on a very active diary.

whatcha entry update / whatcha entry delete

whatcha entry update <entry-id> [--text "..." | --text-file <path|->] [--mine | --all] [--title "..."] [--tag <tag>]...
                     [--image <file>]... [--remove-image <media-id>]... [--cover <file>] [--mood <mood>]
                     [--location "..."] [--lat <deg> --lng <deg>] [--message "..."] [--json]
whatcha entry delete <entry-id> [--yes] [--all] [--json]

Change or take back an entry that is already there (#117), by its id -- whatcha write prints it as entryId, and so does whatcha read --json. Both use the app's own calls: PATCH /entries/{id} (a new version on top of the one just read, so a save that lands in between is refused, never overwritten -- run the command again) and DELETE /entries/{id}. Who may do either is the diary's call; a refusal is the API's own error. Neither needs a terminal, so both run from a server or a scheduled job.

update changes only what you give it; everything else the entry has is saved again as it was, including its time range:

• --text / --text-file <path|-> -- the new text, read the way write reads it (a file, or standard input for -; BOM dropped, CRLF to LF). If somebody else wrote any of the entry's text, replacing all of it needs a choice: --mine replaces only the lines you wrote -- your part, from your first line to your last, as the app's blame shows it -- and leaves everyone else's exactly where it was; --all replaces the whole text, theirs included. With --mine, an empty text removes your part. --mine refuses when your lines and somebody else's are mixed together; edit those in the app.
• --title, --mood, --location, --lat/--lng -- replace the field (same limits as write). --tag (repeat it) -- the entry's tags become exactly these.
• --image <file> -- adds an image after the entry's own; --remove-image <media-id> -- takes one off (read --json lists them as images); --cover <file> -- uploads an image and makes it the cover.
• --message -- a note on the new version, shown in the entry's history.

--json prints entryId, headCommitId, text (mine, all or unchanged), title, tags, images and coverMediaAssetId.

delete asks before deleting when there is a terminal to ask at; --yes skips the question. With no terminal (a pipe, a server, an agent) and no --yes, it deletes nothing and fails -- a script has to say --yes. An entry somebody else also wrote in is not deleted without --all, since that would delete their writing too; take back only your part with whatcha entry update <id> --mine --text "" instead. --json prints entryId, diaryId and deleted. A declined question exits with status 1 and deletes nothing.

whatcha profiles / whatcha switch / whatcha profile-add / whatcha profile-rm

whatcha profiles [--json]
whatcha switch <@handle> [--json]
whatcha switch --account [--json]
whatcha profile-add <@handle> --name <display name> [--avatar <file>] [--json]
whatcha profile-avatar <@handle> <file> [--json]
whatcha profile-rm <@handle> [--json]

Sub-accounts (#1538): one login, more than one profile. A sub-profile is an ordinary user with its own @handle, so after a switch write, read and diaries all act as that profile -- none of them takes a flag, and none of them knows the feature exists. The saved session simply is that profile.

profiles marks the current one with * and labels the account; --json adds remaining, how many more the plan allows.

Which profile is "current" is always the server's answer (GET /me with the saved credential), never an id remembered in the credential store (#58): switch says "Already writing as" only when the server agrees, switch --account signs the account's credential back in on the spot and records who it is, and whoami repairs a saved session whose remembered id had drifted from its credential (as 0.4.0's switch --account left it).

profile-add (#1699) creates one (POST /me/profiles, as the app's "Add a profile" does): a @handle of 3-30 letters, digits, _ or - starting with a letter or digit, and a --name of at most 80 characters. A taken handle or a full plan is the API's refusal. It does not switch -- run whatcha switch <@handle> for that. --avatar <file> (JPEG, PNG, WebP, GIF or AVIF, at most 5 MB, checked before anything is created) is set as the new profile itself would set it: POST /me/avatar with a session for the profile, used once and never saved. If the profile is created but the avatar fails, the profile stays, avatarError says why and the exit status is 2. --json prints profile (id, username, displayName, avatarUrl, parentProfileId) and avatarError (null, or {code, message}).

profile-avatar (#50) changes the avatar of a profile that already exists, with the same checks. The profile in use sets its own; another sub-profile is set through a session for it, used once, as profile-add does. The account's own avatar cannot be reached from a sub-profile -- switch --account first. --json prints profileId and avatarUrl.

switch --account is how you come back. The API refuses to mint an account session from a sub-profile's session on purpose -- a sub-profile that could ask for one would be a way to take the account over -- so switch sets the account's refresh token aside in the same credential store and --account spends it. Switching from one sub-profile to a sibling carries it forward unchanged. Logged in with a personal access key, it is the key that is set aside (accountKey), and --account goes back to it.

profile-rm deletes a sub-profile and everything it wrote; the API refuses the account itself and the profile currently in use.

Billing is the one thing a sub-profile does not have: the account's plan is its plan, and a sub-profile's own limits are the account's.

whatcha wiki

whatcha wiki list [--search <text>] [--group <group-id>] [--limit N] [--cursor <c>] [--json]
whatcha wiki read <page> [--group <group-id>] [--json]
whatcha wiki write <page> --text "..." [--image <file>]... [--cover <file>] [--replace] [--message "..."] [--group <group-id>] [--json]
whatcha wiki cover <page> <file> | --clear [--group <group-id>] [--json]

The Experience Wiki (#1664), on the app's own routes: Public Square's /experience-pages, or with --group that group's /groups/:groupId/experience-pages (#1348; whatcha diaries --json shows each diary's groupId). <page> is the page's tag, e.g. "Kyoto Tower" (a leading # is dropped). Who may read or write which page -- group membership, a page's Owner and edit policy (#1344), a lock -- is the API's call; a page this account cannot see reads as found: false, any other refusal is printed as the API sent it.

wiki write appends below the page's current text and creates the page if it does not exist; --replace saves the text as the page's new version instead. Either way every earlier version stays in the page's history. The wiki's PUT takes no expected revision, so if somebody else saves between write's read and its PUT, that is reported (concurrentEdit: true, a warning on stderr, exit status 2) rather than passed off as a clean save -- their version is in the history to merge back.

Images (#1667). --image <file> (repeatable) uploads a local image and appends ![<file name>](media:<mediaAssetId>) for it below the text, in the order given, one paragraph each; with images, --text may be left out. --cover <file> uploads an image and makes it the page's cover in the same save. wiki cover <page> <file> sets the cover of an existing page on its own, and wiki cover <page> --clear removes it. Uploads go through the app's own flow (POST /uploads into the page's group -- Public Square's for the public wiki -- the PUT to the signed URL, then POST /uploads/:id/complete), so the server's limits apply: JPEG, PNG, WebP, GIF or AVIF, at most 40 MB, within the account's storage quota. Both are checked before anything is sent -- the type from the file's first bytes, not its name -- and so is the page's 20,000-character limit, so a bad file or an over-long page uploads nothing. wiki read lists each image's signed URL (valid for about an hour) after the text, and the cover's above it; --json adds media (id, url, mimeType, altText), coverMediaAssetId and coverUrl. wiki write --json reports images (file, mediaAssetId) and coverMediaAssetId.

The --json contract

Every command accepts --json. On success it prints exactly one JSON object to stdout: {"ok": true, ...}, with the fields documented per command above (diaries, entryId/mode/verified/title/tags/titleKept for write, body/title/tags/... for read, entryId/text/deleted for entry, pages / body / mode/concurrentEdit for wiki, profile/avatarError for profile-add, diary/members for diary-new, url/isPublic for publish). On failure it prints {"ok": false, "error": {"code", "message"}} -- still to stdout, so a script doing whatcha ... --json | jq gets parseable JSON either way, without also having to capture stderr.

Never included, on success or failure: an access token, a refresh token, a personal access key, or a password. whatcha login --json's output is {"ok", "userId", "email", "credentialStore"} (plus "authKind": "key" for a key) -- the store's name, never its contents.

Tests

npm ci
npm run typecheck
npm test

Every test runs with no network: tests/fixtures/fake-client.ts implements the same WhatchaClient interface the real HTTP client does, so src/lib/append-entry.ts, the command parsers, and the token store are all exercised against an in-memory fake instead of a live API. The token-store tests point WHATCHA_CONFIG_DIR at a throwaway directory rather than touching a real OS keychain or the developer's own config file.