#The lore CLI

lore is the command-line client for Lore: it signs in to an instance, reads and writes quests and folios, and builds, pushes and deploys apps from a laptop or a CI job. This page lists every command group with what it is for and the flags you will reach for first; lore <command> --help has the rest.

#Install

npm install -g @alepha/lore
lore --help

Inside an Alepha workspace that already depends on @alepha/lore, yarn lore ... works without the global install.

#Signing in

lore login uses the OAuth device flow: it prints an address and a code to enter there. The session is stored per instance in ~/.alepha/credentials.json, refreshes itself, and ends after 30 days without a command, after 180 days at most, or when you revoke it.

When a command runs, LORE_API_KEY wins over a stored login. With neither, the command fails and says how to fix it: it never starts a login by itself, and lore login refuses to run in CI, where nobody could approve the code.

#Choosing the project

Every project command looks for the project in this order:

1. --project <slug> (or -p);
2. the LORE_PROJECT environment variable;
3. the nearest .alepha/lore.json, found by walking up from the current directory.

.alepha/lore.json is written by lore project link <slug> and lore project create <name>, and holds one field:

1{ "project": "my-project" }

#Conventions

• Names follow the MCP tools. The agent tool quest_create is lore quest create. The CLI covers less: a command can take fewer flags than its tool (quest_create has dueAt, lore quest create does not), and some tools have no command (quest_hold, quest_comment_add, folio_update, every epic_*).
• Output is human-readable by default. --output json prints JSON for scripts on the commands whose --help lists it: quests, folios and projects, but not lore deploy or lore secrets, for instance. Logs go to standard error, so piping the output stays clean; a command that only logs, like lore secrets list, leaves standard output empty.
• Long text (descriptions, folio content, messages) can be read from a file with @file, or from standard input with @-, on the flags whose help says so.
• References. A quest is 12, Q12 or '#Q12' (quoted, or the shell treats # as a comment). A folio is F12, an epic 45 or E45. The exception is lore attachments push: --quest and --folio take the bare number.
• Exit codes. 0 success, 1 failure (including a partial write), 3 not signed in, 4 not allowed. A credential Lore rejects (expired or revoked) is 3, and a refused permission 4, on the project, quest, folio, estate, registry and stack commands; the others exit 1 for both.

#Environment variables

#Commands

#Projects

lore project create makes a project with the Deploy and watch apps capability only, its Deploy apps option on and Track apps off. Turn on the rest in the project's settings.

#Quests

See Quests for the statuses and rules behind these.

#Folios

See Folios.

#Attachments

lore attachments push ./chart.png --quest 1208
lore attachments push ./notes.pdf --folio 12 --name "Meeting notes.pdf"

One file per call, onto a quest or a folio. See Attachments.

#Releases

See Releases for how these fit in a release job.

#Quality

lore quality push sends the coverage and test totals of the last run to the project's Quality report. --branch files them under another branch than the checked-out one. It expects an Alepha project.

#Apps and deploys

lore secrets manages the variables a deployed copy runs with. --env is required, and no command ever prints a whole value (list shows a masked prefix):

lore secrets set DATABASE_URL=postgres://... --env production
lore secrets set DATABASE_URL --env production   # value read from $DATABASE_URL
lore secrets set --file .env.production --env production
lore secrets list --env production
lore secrets unset DATABASE_URL --env production

See Deploying an app for the whole flow.

#Artifacts

See Artifacts.

#Estates

See Estates.

#Container registries

#Stacks

A stack is a group of apps and services deployed together from one compose.yml onto a Bay estate.

--name picks the stack and defaults to the project slug. See Stacks for Lore's side, and Stacks in the Bay documentation for the file's format.