Creating an Encore App
Instructions
Do the steps in order.
1. Check before creating
- CLI:
encore versionprints a version. If not, seeencore-install. - Login: if the app should deploy to Encore Cloud,
encore auth whoamimust printlogged in as <email>. If not, seeencore-login. Skip the login only if the user wants a local-only app. If you can't tell, ask. - Auth key only (
logged in as app <app-id>): don't runencore app create, it fails. Ask the user to create the app in the Cloud Dashboard, then follow Get an existing app. - Already in an app: if the current directory or a parent has an
encore.appfile, the app exists. Don't create another one.
2. Pick a template
| The user wants | Encore.ts | Encore.go |
|---|---|---|
| A small working app (default) | ts/hello-world |
hello-world |
| An empty app, no services | ts/empty |
empty |
| A REST API with a SQL database | ts/url-shortener |
url-shortener |
| Several services, SQL databases, Pub/Sub, cron jobs | ts/uptime |
uptime |
| A GraphQL API with a SQL database | graphql |
--example also takes any directory in https://github.com/encoredev/examples, or a GitHub URL: https://github.com/<owner>/<repo>/tree/<branch>/<path>.
3. Create it
encore app create my-app --example=ts/hello-world # Encore.ts
encore app create my-app --example=ts/empty # Encore.ts, empty
encore app create my-app --example=hello-world # Encore.go
encore app create my-app --example=empty # Encore.go, empty- Always pass
--example. In a terminal, the CLI asks for a language and template when it's missing. Without a terminal, which is how agents usually run commands, it can't ask, and creates an empty Go app, even for a TypeScript project. - Name: lowercase letters, digits, and single dashes, at most 50 characters, not starting or ending with a dash. It becomes the directory, which must not exist yet.
- It takes a while: it downloads the template and runs
npm installorgo get. Wait for it to finish.
Optional flags:
--llm-rules=<tool>: adds Encore's coding instructions for an AI tool and configures the local Encore MCP server for it. One ofcursor,claudecode,vscode,agentsmd, orzed.--org=<id-or-slug>: creates the app in an org instead of the user's personal account.--platform=false: creates a local-only app even when logged in.
4. Check the result
The output ends with Successfully created app <name>!.
- Logged in: it also prints
App ID: <app-id>andWeb URL: https://app.encore.dev/<app-id>. The app ID can differ from the name. The app has an initial commit and anencoregit remote, so it's ready to deploy. - Logged out:
encore.apphas an empty"id", and there's noencoreremote. To link it to Encore Cloud later, seeencore-link-app.
Then cd <name> and run the app (see encore-run).
Get an existing app
On Encore Cloud:
encore app clone <app-id> [directory]. It adds theencoreremote. The app ID is in the Cloud Dashboard URL,app.encore.dev/<app-id>. If the app is linked to GitHub,git clonethe GitHub repository instead.Code with an
encore.appfile: it's already an app. Run it (seeencore-run).Encore code without an
encore.appfile: register it in place, from its root directory. Always pass--lang, or the app is treated as Go.encore app init my-app --lang ts # --lang go for Encore.go
Errors
directory <name> already exists: pick another name, or ask before removing the directory.this directory already contains Encore code but isn't initialized as an app: useencore app init(see above) instead of creating a new app.specify an app name: pass the name as the first argument.name must only contain lowercase letters, digits, or dashes, or another name error: fix the name.--org requires being logged in and --platform: log in, or drop--org.creating app on encore.dev: ...: runencore auth whoami. If it printslogged in as app <app-id>, an auth key can't create apps: a person must log in (seeencore-login).npm installfails: the app is still created, without dependencies. Install Node.js (seeencore-install), then runnpm installin the app.
Guidelines
- Don't run
encore app createto deploy or link an existing app. It creates a new, separate app. - Next: run the app (
encore-run), build it out (encore-serviceandencore-api, orencore-go-serviceandencore-go-api), and deploy it (encore-deploy). - Docs: https://encore.dev/docs/quick-start and https://encore.dev/docs/cli/cli-reference