# Create a new Encore app

This guide is for coding agents. Follow it to create a new [Encore](https://encore.dev) app, check that it runs locally, and deploy it.

To use it, tell your agent: `Read https://encore.dev/agents/getting-started.md and follow it to create a new Encore app.`

When you're done, the person you're working for has a new Encore app that builds, runs with `encore run`, answers a request, passes its tests and is deployed to Encore Cloud. Your agent also has Encore's rules and skills installed in it.

## Rules

- **Order:** Run the steps in order. Skip a step when its check shows it's already done.
- **Commands:** The commands below use flags that keep them from prompting for input. Run long-running commands, like `encore run`, in the background.
- **Failures:** If a step fails, stop. Show the person the command, its error output and what you think went wrong.
- **Interactive prompts:** If a command prompts anyway, never answer it for the person (account, organization, credentials, confirmations). Ask them.
- **Location:** Create the app in the current directory unless the person names another one. Never create it inside another git repository's working tree unless they ask for that.

## Inputs

Take these from the person's request. Ask only for what you can't work out.

- **Language:** One of the languages Encore supports. Use what they asked for, or the language of the code around you. If neither tells you, ask them, listing the supported languages (see step 3).
- **App name:** Lowercase and hyphenated, for example `my-app`. If they didn't give one, pick a short name from what they want to build.

## 1. Install the Encore CLI

Skip this step if `encore version` works. Otherwise install it:

- **macOS:** `brew install encoredev/tap/encore`
- **Linux:** `curl -L https://encore.dev/install.sh | bash`. The binary goes to `~/.encore/bin`. Add that to `PATH` if `encore` isn't found.
- **Windows (PowerShell):** `iwr https://encore.dev/install.ps1 | iex`

Then check that `encore version` works.

## 2. Ask the person to log in

Skip this step if `encore auth whoami` shows a logged-in user.

Logging in registers the app on Encore Cloud and gives it an `encore` git remote for deploying. Only the person can do it. Ask them to run `encore auth login`, which opens a browser where they log in or sign up. Without a browser, they can set the `ENCORE_AUTH_KEY` environment variable to an Encore auth key instead, and the CLI logs in with it. Continue with step 3 while they log in.

## 3. Choose the language and check prerequisites

Run `encore app create --help`. The `--lang` flag lists the languages your CLI supports. Settle the language with the person now, if their request didn't.

Then check the prerequisites for that language. The quick start lists them: https://encore.dev/docs/quick-start.md

- **Language toolchain:** Check that it's installed. If it's missing, ask the person before you install it.
- **Docker:** Run `docker info`. A new app runs without Docker, but Encore needs it to run databases and other infrastructure locally once the app declares any. If it's missing or not running, tell the person and continue.

## 4. Create the app

Skip this step if `<app-name>/encore.app` already exists.

**Login:** Before you create the app, check that `encore auth whoami` shows the person's user. If it doesn't yet, remind them to finish logging in. If they don't want to log in, add `--platform=false` to the command below. They can link the app to Encore Cloud later (the `encore-deploy` skill covers this).

**Template:** Start from the Hello World template for the language. The templates the CLI offers are listed, with the language of each, in https://raw.githubusercontent.com/encoredev/examples/main/cli-templates.json. Use the `template` value of the "Hello World" entry for your language. If there's none, leave out `--example` to create an empty app.

```bash
encore app create <app-name> --lang=<lang> --example=<template> --llm-rules=<rules>
```

**Rules:** For `<rules>`, `encore app create --help` lists the supported agents, for example `claudecode` for Claude Code and `vscode` for GitHub Copilot in VS Code. Use the one for the agent you are, or `agentsmd` if yours isn't listed. This writes Encore's rules into the app, and for some agents it also configures Encore's local MCP server.

**Organization:** If the command asks which organization to create the app in, ask the person, then run it again with `--org=<org>`.

`encore app create` prints the commands for running and testing the app. Note them for step 6.

## 5. Install Encore's agent skills

In the app directory, run:

```bash
npx skills add encoredev/skills --skill '*' -a <agent> -y
```

Set `<agent>` to your agent's ID in the skills CLI, for example `claude-code`, `cursor`, `codex` or `github-copilot`. The skills cover APIs, databases, Pub/Sub, cron jobs, auth, testing, deploying and more.

Most agents load new skills and MCP servers only when a session starts. If that applies to you, don't stop. Tell the person they can restart you in the app directory to pick them up, and continue. Until then, find each skill's `SKILL.md` under the app directory and read it when you need it.

## 6. Verify it runs

From the app directory:

1. Start the app with `encore run` in the background, and wait until it prints the API URL (`http://localhost:4000` by default).
2. Call one of the app's endpoints with `curl`, at the URL `encore run` printed. Find an endpoint in the app's code or README. It should return a successful response. If you created an empty app, add one small endpoint first, following the language's docs, and call that.
3. Stop `encore run`, unless the person wants to keep it running.
4. Run the tests with the test command `encore app create` printed. Set `CI=true` for it, for example `CI=true encore test`, so the test runner doesn't start in watch mode. The tests should pass.

If any of these fail, stop and show the person the output.

## 7. Deploy

Deploying is a commit and a push. When the person is logged in, `encore app create` has already made the first commit and added an `encore` git remote, and pushing to it makes Encore Cloud build, test, provision and deploy the app. A new app has one environment, `staging`, which is free development hosting on Encore Cloud and deploys from the app's main branch.

If the app was created with `--platform=false`, it isn't linked to Encore Cloud yet. Skip this step, and tell the person in step 8 that they can link it once they've logged in (the `encore-deploy` skill covers this).

1. Check that `git remote -v` lists `encore`.
2. Commit anything you've changed since the app was created: `git add -A && git commit -m "<message>"`.
3. Run `git push encore`. A successful push prints a line like `remote: <branch>: triggered deploy https://app.encore.dev/<app-id>/envs/staging/deploys/<id>`. If it doesn't, nothing was deployed. `Everything up-to-date` means there was nothing new to push.
4. The push returns as soon as the deploy starts. The first deploy takes a few minutes while Encore provisions the environment. Its progress is at the URL the push printed.
5. When it's done, the API is served at `https://staging-<app-id>.encr.app`, with `<app-id>` being the `id` field in `encore.app`. Call the same endpoint you called locally there. It should return the same response.

The deploy runs the app's tests, and failing tests block it. If the push hangs, the network may be blocking SSH to `git.encore.dev` on port 22. For other failures, see https://encore.dev/docs/platform/deploy/troubleshooting.md

**Deploying again:** Every commit pushed to the main branch deploys again: `git add -A && git commit -m "<message>" && git push encore`. If the app declares secrets, each one needs a value in the environment before you push, or the deploy fails. The person sets them with `encore secret set --type dev,local <name>`, which prompts for the value.

## 8. Hand over

Tell the person:

- Where the app is and how to start it (`encore run`).
- That the local development dashboard runs at `http://localhost:9400` while the app is running, with API docs, traces and database explorers.
- The staging URL, the deploy's URL in the Cloud Dashboard, and that every push to the main branch (`git push encore`) deploys again.
- Anything you skipped or couldn't verify, such as Docker not running or not being logged in.

Then ask what they want to build, or start on it if their request already said. Use the skills from step 5 for the work, and these references for the details:

- **Docs index:** https://encore.dev/llms.txt lists every docs page as markdown, grouped by language.
- **Deploying:** https://encore.dev/docs/platform/deploy/deploying.md
- **Fixing a failed deploy:** https://encore.dev/docs/platform/deploy/troubleshooting.md
- **Local MCP server:** https://encore.dev/docs/mcp.md
- **Encore skills:** https://github.com/encoredev/skills
- **Migrating an existing app instead:** https://encore.dev/agents/migrate.md