Docs

Commands reference

Every evlet command in Evlet 0.4.3, grouped by what you use it for. Each entry gives what it does, its usual form and the options you are most likely to need. Run evlet <command> --help for the full list.

#How commands find your project

Run project commands from inside the project folder, or any folder below it. Evlet finds the project from there and runs the command with the project's own Evlet. To work on a project from somewhere else, add --project /path/to/myproject before or after the command.

Commands that load your apps' code ask whether you trust it first. In scripts, where nobody can answer, review the code and add --trust.

#Project and apps

#evlet setup

Creates a project: apps/, instances/ and its own .venv with Evlet in it. It can also create apps and an instance, install them and start the site, in one go.

Terminal
evlet setup myproject
evlet setup myproject --app notes --instance acme --dev
OptionMeaning
--app NAMESCreate these apps, as a comma list such as notes,crm.
--get GIT_URLSFetch these apps from Git, as evlet app --get does.
--instance NAMECreate this instance and install the apps on it.
--devThen start evlet dev and print a sign-in link.
--host HOSTNAMEInstead, prepare a public site: a Caddy site and a systemd service for this hostname. It asks for the Administrator's password.
--applyWith --host: also run the sudo steps it prints, showing each one first.
--port PORTThe port for --dev or the service. The default is 8000.
--trustTrust the app code for the whole run instead of asking.

If a step fails, fix the cause and run the same command again. Finished steps are skipped.

#evlet app

Creates a new app in apps/, fetches one from Git, or lists the apps.

Terminal
evlet app notes
evlet app --get https://github.com/company/notes.git
evlet app --list
OptionMeaning
--get GIT_URLFetch an app from Git. It checks the files first, then asks for trust before it runs or builds any code.
--listList the project's apps with their version and title.
--legacyCreate the older nested app layout, with hooks.py.
--trustTrust the fetched app's code without asking.

#evlet build

Prepares every app in the project and checks it, without opening any instance's database. install and migrate build as well, so you rarely need it on its own.

Terminal
evlet build --trust

#evlet install

Installs an app on an instance. It makes a backup, then creates or changes the database.

Terminal
evlet install notes --instance acme
OptionMeaning
--instance NAMEThe instance to install on. Required.
--trustTrust the app and its dependencies without asking.
--yesServe each new website on its suggested host without asking.
--no-hostOffer no host for websites that suggest one.

#Instances

#evlet instance

Creates an instance, which is a site with its own database, accounts and files. Or lists them.

Terminal
evlet instance acme
evlet instance --list

#evlet migrate

Brings an instance's database up to date with its apps and with Evlet itself. Run it after you change a model, update an app or upgrade Evlet. It makes a backup first. If any step fails, nothing changes.

Terminal
evlet migrate acme --plan
evlet migrate acme
OptionMeaning
--planShow what would change and suggest a migration. Writes nothing.
--trustTrust changed app code without asking.
--allow-destructiveLet DropField delete retired columns and their values.
--allow-maintenanceLet data steps marked maintenance=True change confirmed and posted records. Each one is audited.
--recompute-postedLet Recompute steps recalculate posted records too.

#evlet makemigration

Writes the migration that migrate --plan suggests into the app's migrations/ folder, as m0001_<name>.py. It never overwrites a file. Review the file before you migrate.

Terminal
evlet makemigration notes --instance acme --name tasks
OptionMeaning
--instance NAMEThe instance whose database the migration starts from. Required.
--name NAMEThe name after the number. The default is changes.

See Migrations for what goes in a migration.

#Serving and hosts

#evlet dev

Runs an instance for development on 127.0.0.1. It reloads when your code changes, runs background jobs, and prints a one-time sign-in link.

Terminal
evlet dev --instance acme
OptionMeaning
--instance NAMEWhich instance. Needed when the project has more than one.
--port PORTThe port. The default is 8000.
--user NAMEMake the sign-in link for this user instead of the Administrator.
--no-linkPrint no sign-in link.

It never applies migrations. When a model change needs one, stop it and run evlet migrate.

Prints a fresh one-time sign-in link for a running evlet dev or evlet playground. Use it in a second terminal when the first link is used or has expired after 10 minutes.

Terminal
evlet dev-link
evlet dev-link --user mariam
OptionMeaning
--user NAMESign in as this user. The default is the Administrator.
--instance NAME, --port PORTWhich running instance, when you have more than one.
--playgroundUse the running Playground, even inside a project.

#evlet serve

Runs an instance for real use. It has no sign-in links and no reloading. It checks that the instance is migrated and that its apps match apps.lock, and refuses to start if not.

Terminal
evlet serve acme
evlet serve acme --jobs --port 8000
OptionMeaning
--jobsAlso run background jobs in this process.
--host HOST, --port PORTThe address and port to listen on.
--debugShow the full error when startup fails.

On a server, the systemd service that evlet setup --host writes runs this command.

#evlet routes

Prints which host and path serve which part of the instance, and where each rule comes from.

Terminal
evlet routes acme

#evlet proxy

Prints a Caddy or nginx configuration for the instance's hosts. It needs a domain, set in Instance(domain=...) in the instance's config.py or in routes.py.

Terminal
evlet proxy acme --caddy
evlet proxy acme --caddy --check
OptionMeaning
--caddy, --nginxWhich server to write for. One is required.
--write PATHWrite the configuration to this file instead of printing it.
--checkCheck that each host's DNS points at this server.
--port PORTThe port the instance listens on.

#evlet host add, remove and list

Manage the extra hosts of an instance, such as a public website on www.example.com.

Terminal
evlet host list acme
evlet host add acme www.example.com --root site.www
evlet host remove acme www.example.com
  • host list prints each host with the frontend it serves at /.
  • host add adds the host to the instance's routes.py, checks its DNS and rewrites the Caddy site. --root APP.FRONTEND names what it serves. Required.
  • host remove takes it out again.
OptionMeaning
--routes-onlyChange routes.py only, for Caddy with on-demand certificates. Then restart the service.
--applyAlso run the sudo steps: install the Caddy site, reload Caddy, restart the service.
--ip IPThis server's public address, for an exact DNS check.

#evlet playground

Runs a demo site with sample data, outside any project. Its data is removed when it stops.

Terminal
evlet playground

#evlet docs

Serves the guides for your installed Evlet version on http://127.0.0.1:8001. It works offline.

Terminal
evlet docs

#evlet restart (coming)

evlet restart is planned for the next Evlet release. This entry will describe it then. Until it ships, restart an instance's service yourself, for example sudo systemctl restart evlet-acme.

#Users and access

#evlet users set-password

Sets a user's password. It asks twice and never shows it. It ends that user's sessions, AI assistant connections and API keys. Use it to give the Administrator its first password on a server.

Terminal
evlet users set-password acme admin

#evlet users set-email

Sets the email address a user gets notifications at.

Terminal
evlet users set-email acme admin ops@example.com

#evlet users reset-two-step

Clears a user's two-step sign-in. They set it up again the next time they sign in. Use it when someone loses their authenticator app.

Terminal
evlet users reset-two-step acme mariam

#evlet controls grant

Makes a user an active admin, from the server's terminal. Use it when nobody can open Controls. It also clears any allowed networks set in Controls.

Terminal
evlet controls grant acme mariam

Links an account to a record, such as a portal user to their customer, so row scopes can use it. --remove takes the link away.

Terminal
evlet link-user acme buyer customer 01jwx8mjp38nw
evlet link-user acme buyer customer 01jwx8mjp38nw --remove

All four user commands and link-user are recorded in the audit log as cli.

#Data

#evlet backup

Makes a backup of an instance: its four database files, as one set, in data/backups/.

Terminal
evlet backup --instance acme
OptionMeaning
--instance NAMEWhich instance. Needed when the project has more than one.
--to DIRWrite the set into this folder instead.

A backup holds the database only. Keep uploaded files, config.py, secret.key and your app code safe as well.

#evlet restore

Puts an instance back to a backup. Stop the instance first. It replaces all four database files, and keeps the files it replaces as a backup of their own.

Terminal
evlet restore instances/acme/data/backups/20261113T071741177131Z.sqlite3 --instance acme
OptionMeaning
--instance NAMEWhich instance. Needed when the project has more than one.
--yes NAMERestore without asking. Give the instance name to confirm.

Name the main file of the set. A backup from an older Evlet asks you to run evlet migrate before you serve it.

#evlet ids check

Reports records with an impossible id, and tables that still allow an id to change. It only reads.

Terminal
evlet ids check acme

#evlet journal verify

Checks the tamper-evident history of records for breaks. It only reads, and exits with an error when it finds one.

Terminal
evlet journal verify acme

#evlet ledger list

Lists each ledger model with its table, its number of rows and its settings.

Terminal
evlet ledger list --instance acme

#evlet effects check

Works out again the rows that records post to other models, and reports any difference from what is stored. It only reads.

Terminal
evlet effects check acme

#evlet jobs list

Lists the newest 100 background jobs with their state, attempts and progress. It works while the instance is running.

Terminal
evlet jobs list --instance acme

#evlet secrets rotate

Writes a new secret.key for the instance and encrypts every saved secret again under it: connector secrets, mailbox sign-ins and two-step secrets. Running instances use the new key straight away.

Terminal
evlet secrets rotate acme

#Connector

These commands connect a terminal or an AI assistant to a running Evlet site over HTTP, as a user, with that user's permissions. They do not need a project.

#evlet login

Signs in to a site and saves a private session file. It asks for the password and never stores it.

Terminal
evlet login --url http://127.0.0.1:8000 --username mariam --session mariam.session

An admin must set up two-step sign-in in the browser before evlet login works for them.

#evlet logout

Ends the session on the site and deletes the session file.

Terminal
evlet logout --session mariam.session

#evlet describe

Prints the models the user may use, with their operations and actions, as JSON. --model NAME describes one model in detail.

Terminal
evlet describe --session mariam.session
evlet describe --session mariam.session --model customer

#evlet mcp

Runs an MCP server for an AI assistant, on standard input and output, as the signed-in user. It offers read tools only, unless you add --allow-writes. The site's permission checks always apply.

Terminal
evlet mcp --session mariam.session

For describe --model and mcp, an admin must turn on Allow MCP for the user in Controls.