#The lore CLI

lore is Lore's command-line client. It signs in to an instance, reads and writes a project's quests, epics, folios and feedback, and builds, pushes and deploys apps from a laptop or a CI job. This page lists every command with the flags it takes; lore <command> --help prints the same list with a sentence for each flag.

#Install

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

A project that already depends on @alepha/lore can run yarn lore ... without the global install.

#Signing in

LORE_API_KEY wins over a stored login. With neither, a 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.

See how agents and the CLI connect for where an API key comes from, how long a login lasts and how to revoke one.

#Choosing the project

Every command that works inside a project looks for it 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": "acme" }

#Conventions

• Names follow the MCP tools. The agent tool quest_create is lore quest create, and every tool has its command. Three subjects are plural here: lore apps, lore artifacts and lore releases. The CLI also does what no tool does: uploading a file, building and pushing an app, and managing secrets, estates and registries.
• Flags left out of the tables. Every command that works inside a project takes --project (-p), and most take --output. The tables below list the others.
• Output is human-readable by default. --output json prints JSON for scripts on the commands whose --help lists it: the planning commands, the estates and most reads, 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.
• A delete needs --yes, and refuses without it rather than prompting: a script has nothing to answer with. Five commands do ask in a terminal, and --yes answers for a script: lore estate rotate, move and delete, and lore stack destroy and delete. lore project delete and lore apps destroy want a name typed again in --confirm instead.
• Long text (descriptions, folio content, comments, a rule's JSON) 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). The same goes for an epic (45, E45), a folio (F12), a feedback item (P120), a blight (B12), a directory (D12) and a folio's attachment (A12). The exceptions take the bare number: --quest and --folio on lore attachments push, and --directory on lore folio create and update.
• Repeatable flags. A flag marked repeatable is passed once per value: --tag bug --tag api.
• 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 is 4, except on the build, push and release-job commands, which exit 1 for both: lore deploy, lore apps build, redeploy and destroy, lore secrets, lore artifacts push and push-image, lore attachments push, lore quality push, and lore releases check, cut, publish and changelog (without --frozen).

#Environment variables

#Projects

The sections of lore project report are summary, flow, backlog, planning, support, knowledge, delivery and team.

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 with lore project capability enable or in the project's settings: see Capabilities.

lore project delete prints what goes with the project first (its quests, folios and deployed copies), whether --confirm matches or not. There is no --yes: the slug is typed twice. Nothing running on an estate is stopped.

#Quests

Worth knowing about the values:

• --status is todo, in_progress, on_hold, completed or shelved.
• --priority is optional, low, medium or high. --size runs from 1 (XS) to 5 (XL) and defaults to 3.
• --waive closes an objective that was not done, with the reason. An objective that was done is ticked with lore quest objective set.
• --accept on lore quest create that is refused leaves the quest created and exits 1.

On lore quest update, a flag replaces what was there:

• --tag replaces the whole set: pass every tag to keep, or '[]' to clear them.
• --objectives takes the whole list as JSON, to reword or reorder it. Carry the id of each objective that survives.
• --epic 0 takes the quest out of its epic, --depends-on 0 clears the dependency and --feedback 0 unlinks the feedback item.
• An empty string clears --due-at, --completion-message and --release.
• --expected-updated-at takes the updatedAt of your last read: an edit that landed since is refused rather than overwritten.

See Quests for the statuses and rules behind these.

#Epics

See Epics, and Reviewing an epic for what a review holds.

#Releases

Every command names its release by --tag (-t), byte for byte.

Four commands serve a release job:

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

The others manage the release's own record:

Two of these lose something:

• --new-tag moves the release's URL and breaks every link already shared. There is no redirect.
• lore releases delete on a published release also deletes its frozen changelog and counts, which exist nowhere else.

See Releases for how these fit in a release job.

#Folios

A pinned folio's whole content opens every lore project context, so pin sparingly.

See Folios.

#Directories

--cascade also deletes everything the directory holds: its folios, their attachments and its directories.

#Attachments

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

lore attachments push <file> puts one file per call onto a quest or a folio.

A folio adds a suffix to a name it already holds, and the command prints the name it stored. To read a file back, use lore quest attachment get or lore folio attachment list. See Attachments.

#Feedback

--status is pending, accepted, rejected or all. Accepting creates no quest: file one with lore quest create --feedback <ref>.

See Feedback.

#Automations

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

--state is disabled, active, paused or broken. A <policy> is quest-reminders or release-notifications. catalog, test and adoption preview always print JSON.

See Automations.

#Blights and insights

Before resolving a blight, check lore insights read --segment errors: it is what says whether the failure is still happening.

See Telemetry.

#Quality

lore quality push sends the coverage and test totals of the last run to the project's Quality report. It reads coverage/coverage-summary.json and coverage/test-results.json, the two files alepha test --coverage writes. --branch files the run under another branch than the checked-out one.

#Apps and deploys

These commands build and deploy the app in the current directory, which has to be an app built with the Alepha framework. A stack deploys any Compose file.

• --app defaults to LORE_APP, then to the name in package.json.
• --env on lore deploy falls back to LORE_ENV, then to the app's environment when it has exactly one. lore apps destroy never guesses it.
• --env on lore apps build builds what that environment can run.
• --suffix starts with a dash, so write it with =: --suffix=-staging.
• --sigil forces a sigil for the copy and stores its key in the copy's environment. A build that declares SIGIL_KEY gets one without the flag.
• lore apps destroy keeps the copy's data, with one exception: a copy created as ephemeral on Cloudflare loses its database and its bucket too.
• --purge is for a copy on a Bay whose data should go as well. Lore never asks a machine to delete data: the flag sends nothing, and prints the bay remove --purge command to run on the machine.
• --acknowledge-migrations is required when migrations landed since that run: the old build will run against the current schema.

See Deploying an app for the whole flow.

#App instances

An instance is one deployed copy of an app, named by --app and --env. Both are required on every command here but list: neither is ever guessed. See Apps and instances.

lore apps instance delete undeploys nothing, and is refused while the copy still runs: take it down with lore apps destroy first. --estate names an estate lent to the project; pass it or --estate-id, not both. An empty --url clears the pinned address.

#Sigils

A sigil is the key one copy reports its telemetry with. See Telemetry.

create and rotate print the token once, and nothing can show it again. To revoke a leaked token, use rotate: delete throws the history away.

#Secrets

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

--file (-f) sets every key of a dotenv file, SIGIL_KEY aside. --app names another app than the current directory's.

#Artifacts

latest is the one tag that may be replaced. --force moves any other tag that already holds different bytes, or names a different image. --digest is checked: the push is refused if the registry reports another one. An image on ghcr.io is read anonymously; any other registry needs the project's credential first, see Container registries. --format is archive or image.

See Artifacts.

#Estates

An estate is a machine a project deploys onto.

Provisioning. --provider scaleway buys the server through the provider's own CLI: it needs scw installed and scw login done. Without --provider the command lists the providers and what each needs. --project is the project the estate belongs to, created with the Deploy and watch apps capability when it does not exist; a project that has it off is refused before anything is bought. --name defaults to three random words, --type and --zone to the provider's, and --timeout to 300 seconds. A provisioned estate accepts deploys unless --no-allow-deploys.

Adding a machine by hand. lore estate add leaves deploys off unless --allow-deploys: a new machine reports stats only until someone who manages it says otherwise. With --output json it prints id, slug, deployAllowed, lore, secret and command, so a script can read .secret. lore estate rotate prints the same shape, and the old secret stops working at once.

Expiry. --ttl takes a duration such as 30m, 2h or 3d. Past it the estate shows as overdue and you are told once; Lore stops nothing. On lore estate update, --ttl counts from now and --ttl none clears it.

Deleting. lore estate delete is refused while an app, a stack or a stack environment deploys to the estate. A provisioned estate's server is terminated with its IP and its disk; --keep-server leaves it running, and billing. For a machine added by hand, Lore forgets it and nothing on it stops.

Which estate a slug means. A slug is unique inside a home project. A managing verb (update, rotate, move, delete) resolves it among the estates the project is the home of; a reading verb (get, wait, stats) and lend among the estates you can read, and --home <project> picks one when two share the slug.

See Estates.

#Container registries

A project stores one credential per registry host. Private images are pulled with it: by lore artifacts push-image to verify them, and by the estate at deploy.

The token is never typed inline: it comes from standard input (--password-stdin, as docker login does) or from a file (--password @file).

#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. --env (-e) picks the environment.

On lore stack deploy:

• An environment is created on its first deploy. --estate then picks its estate instead of the stack's default.
• --revision deploys that revision instead of the newest. Without it or --file, the compose file in the current directory is uploaded.
• --app deploys one member app alone, blue/green, from a stored build. --tag names the build and defaults to latest.
• --test-hostname <service> also serves that service on <env>-<stack>.<ip>.sslip.io: HTTPS with no DNS to set up.
• --dry-run says what would happen and changes nothing.

lore stack secrets set --generate makes a random value on the server for the key you name; --length sets its size in hex characters, 16 to 256, 64 by default.

lore stack destroy --purge is for an environment whose volumes should go as well. Lore never asks a machine to delete data: it forgets the environment and prints the bay stack destroy --purge command to run on the machine. lore stack delete is refused while an environment remains, and changes nothing on a machine.

See Stacks for Lore's side, and Stacks in the Bay documentation for the file's format.

#Next

• How agents and the CLI connect
• MCP tools
• Deploying an app
• Quests