#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. Planning is covered: projects, epics, quests, folios and directories. Some tools have no command yet (feedback, automations, blights, sigils, app instances and release management), and a command can still take fewer flags than its tool (quest_create has dueAt, lore quest create does not).
• A delete needs --yes. Nothing here prompts: an agent's shell has nothing to answer with.
• 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

lore quest update also takes --epic (0 takes it out) and --depends-on (0 clears it); lore quest create takes --depends-on.

See Quests for the statuses and rules behind these.

#Epics

#Folios

See Folios.

#Directories

#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.

The release's own record is here too, each naming it by --tag:

lore releases changelog --frozen prints a release's changelog as Lore holds it, published ones included. Without it the command serves a release job, and refuses a published or incomplete release.

#Feedback

A reference is 120, P120 or '#P120'.

#Blights and insights

A reference is 12 or B12.

#Automations

A rule is JSON, usually in a file (--rule @rule.json): lore automation catalog names what it may hold. Every write takes the --expected-revision you read, so a rule edited since is refused rather than overwritten.

#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

The deployed copies themselves, each named by --app and --env:

A sigil is the key one copy reports with:

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.