Commands

Version 0.5.0. Requires Node.js >=20.0.0. Zero runtime dependencies.

Commands

Command	What it does
postlyra login	Sign in through the browser, store an API token, and pick a brand.
postlyra init	Interactive setup: API URL, folders for --all, notes folder, mining window, max ideas.
postlyra brands	List the account's brands. * marks the selected one.
postlyra brands use <brand-id>	Pick the brand this machine mines into.
postlyra mine	Mine the repo you are in, or the repos directly inside this folder, into content ideas. --all mines every configured folder.
postlyra status	Check auth, brand, folders, vault, and the unmined-item count.
postlyra upgrade	Upgrade the CLI to the latest published version.
postlyra --version	Print the installed CLI version.

login options

Flag	Meaning
--with-password	Sign in with email and password instead of the browser. For a machine with no browser to open.

mine options

Flag	Meaning
--all	Mine every configured folder plus your notes folder, wherever you run it. Without it, mine covers only the folder you are in.
--brand	Mine into this brand for one run, overriding the configured brand.
--days	Override the configured mining window, in days.
--dry-run	Collect and filter only. Prints the work log, skips the AI call and the push.
--json	Machine-readable output instead of the friendly terminal summary.
--max	Override the configured maximum ideas for this run.
--no-vault	Leave the notes folder out: with --all, or when you run mine inside it.
--vault	Also mine your notes folder: the configured one, or the path given (--vault ~/notes). With --all, a path replaces the configured one.

postlyra login

Opens Postlyra in your browser, the same shape as gh auth login. You approve the sign-in in the session you are already in (two-factor and passkeys included), the CLI receives the token on a loopback callback (http://127.0.0.1:<port>/callback, PKCE-protected, so the code never leaves your machine), and stores it. The token appears on Profile → API tokens named after the machine that asked, e.g. postlyra-cli (studio-mini); signing in again from the same machine replaces that token and leaves your other machines alone.

postlyra login --with-password prompts for email and password (hidden), then a two-factor code if 2FA is on: for a container, an SSH session, or anywhere no browser can open. It is also the automatic fallback against a Postlyra server that predates the browser flow.

If the account has several brands it shows them as an arrow-key menu and asks which one this machine mines into (without a terminal it asks you to type the name). Choosing nothing leaves no brand selected, and mine will refuse until you run postlyra brands use "<name>".

A failure to list brands does not fail the login. The token is already saved.

postlyra init

Interactive setup. Every prompt shows the current value in brackets, and blank keeps it. Type - at the vault prompt to clear a configured vault.

It writes the config and prints it back with the token masked. No API calls.

Folders are optional. Only postlyra mine --all uses them, so a machine that only ever mines the repo it is in can leave them blank.

Errors it will refuse on: an empty API URL, a non-positive day count, a max-ideas below 1.

postlyra brands

postlyra brands                # list, * marks selected
postlyra brands --json         # {"brands": [...], "selected": "..."}
postlyra brands use "<name>"   # switch. Named, not id-ed: the id also works,
                                # but nobody says "mine into b0f3edb5-..."

postlyra mine

The main event. It works on the folder you run it in:

Where you run it	What it mines
Inside a repo, from any subfolder	That repo
A folder of repos, like ~/Sites/myproduct	Every repo directly inside it
Inside your notes folder	Your notes, not the folder's own commits
A folder with no repo in or around it	Nothing. It stops and suggests --all
Anywhere, with --all	Every configured folder, plus your notes folder

It never widens on its own. A run in the wrong place stops with a message rather than quietly mining everything.

Your notes join a plain run only when you ask: --vault for the configured notes folder, --vault <path> for another one.

A repo gets the same label, and so the same refs, whether you mine it from inside or with --all. Mining it both ways never pushes the same commit twice.

In order:

1. Work out what is in scope (the table above), and resolve the brand: --brand, then the configured brand, then the account's only brand.
2. Collect commits from the repos in scope for the window, plus your notes if they are in scope.
3. Fetch GET /ideas/mining-context and drop everything whose ref is already known.
4. Stop here if --dry-run.
5. Send the filtered work log to your AI backend.
6. Push the result in chunks of 25.

Output per section looks like myrepo: 14 commit(s), 6 already mined, 8 new.

If nothing is left after filtering it prints nothing new to mine and exits 0 without calling the AI.

Useful invocations

postlyra mine                       # the repo you are in
postlyra mine --all                 # every configured folder, plus your notes
postlyra mine --vault               # this repo, plus your notes
postlyra mine --dry-run             # see what would be mined, spend nothing
postlyra mine --dry-run --json      # the same, machine-readable
postlyra mine --days 14             # widen the window for one run
postlyra mine --all --no-vault      # every configured folder, commits only
postlyra mine --max 3               # fewer, better ideas
postlyra mine --brand "<name>"      # a different brand, this run only

An option mine does not know is an error, not something it quietly ignores. postlyra mine --help prints the usage.

postlyra status

Reports auth, brand, folders, vault and the unmined-item count. The count covers every configured folder, which is what mine --all would see. It never throws for missing config, it reports the problem and exits 0, so it is safe in a shell prompt or a health check.

Add --json for a machine-readable version.

postlyra upgrade

Runs npm install -g @postlyra/cli@latest. It deliberately does not print the new version afterwards, because the old code is still loaded in memory. Run postlyra --version to confirm.

Exit codes

Code	Meaning
0	Success, including "nothing new to mine"
1	Any error, or an unknown command
130	Ctrl-C during a password prompt