Getting started
Quickstart
Go from no account to a live app with a Postgres database in a few minutes.
This page walks you from nothing to a live app with a database. Each step shows how to do it in the dashboard, from your terminal, and as a prompt to your AI agent, so pick whichever suits you. You can mix them: an agent can pick up a project you started in the dashboard.
Just looking? After signing in, press Try a demo to get a demo project with $2 of play money. Deploy a template or a function in it and see how everything works. Play money can't be withdrawn or spent on domains, and the demo is deleted after a day unless you press Keep this project (you can restore a deleted demo for 7 days). Keeping it removes what's left of the play money; any credit you added stays.
The fastest way: after signing in, paste your GitHub link into Put something online on the Projects page and press Deploy. CLI makes the project, reads the repo, adds any database it needs and deploys. It only asks you for values it can't fill in itself, like an API key. No code yet? Pick a starter under the box instead. See New to hosting? Start here for what happens at each step.
1. Sign up
In the dashboard: open the dashboard and sign in with your email (you get a 6-digit code or a one-click link, no password), with GitHub, or with a wallet. There's no separate sign-up step.
From your terminal: install the @clicloud-app/cli package from npm, then sign in with an email code:
cli login --email [email protected]For CI, use cli login --token cli_… or set CLI_TOKEN.
Ask your agent: an agent with a wallet signs in with it, and the wallet is its account. An agent with a key from your dashboard is already signed in. See Connect your AI agent.
2. Create a project
In the dashboard: the setup screen asks you to name your project. Later projects are created from the projects list.
From your terminal: in your app's folder, run:
cli init my-appThis creates the project and links the folder to it (in .cli.json), so later commands know where to go.
Ask your agent:
"Create a CLI project called my-app for this repo."
With the API:
POST /v1/projects{ "name": "my-app" }3. Add credit
Your project needs enough credit to cover an hour of whatever you start. A small app costs a few cents an hour, so $5 to $10 goes a long way. If the CLI server you use offers welcome credit, your first project already has some (see /docs/billing).
In the dashboard: the setup screen's Add credit step takes a card (the card fee is added on top, so $10 buys exactly $10 of credit). You can skip it and add credit later from Usage and credit on the project.
From your terminal:
cli topup 10This opens a card checkout. cli deposit shows the project's USDC deposit address instead.
Ask your agent:
"Add $10 of credit to my-app. Pay over x402 if you can, otherwise give me a link."
An agent with a funded wallet pays in USDC on Base or Solana. If it can't pay, it gives you the project id and a link to pay yourself. See Credit, pricing and billing.
4. Deploy your app
Your app must listen on the port in the PORT variable, on host 0.0.0.0, and answer GET / with a 2xx status. Most frameworks do this already if you read PORT.
In the dashboard: choose New service, then GitHub repo (press Connect GitHub once, choose which repos CLI can see, then pick one from the list; it deploys on every push), Public git URL, or Docker image. Press Create and deploy.
From your terminal: from your app's folder:
cli upcli up packs the folder (skipping anything in .gitignore or .cliignore), uploads it, builds it and shows the deploy until it's live. Uploads are scanned for secrets such as .env files; if it finds any, move the values into variables (step 6) and try again.
Ask your agent:
"Deploy this repo to CLI as a service called web."
With the API:
POST /v1/projects/:id/services{ "name": "web", "source": { "type": "git", "repo": "https://github.com/acme/shop", "branch": "main" }, "port": 8080 }Then start a deploy with POST /v1/services/:id/deploys and poll GET /v1/deploys/:id until it's healthy, failed or cancelled.
5. See the URL
Once the deploy is live, your app is at https://web-<id>.<app domain>.
In the dashboard: the URL is on the service's card in the project map and at the top of the service page.
From your terminal:
cli status
cli openAsk your agent:
"What's the URL, and what does it cost per hour?"
If the deploy failed, the service page (or cli logs --deploy <id>) shows one error code with the line from the logs that caused it, such as PORT_MISMATCH or MISSING_ENV. See Deploying for what each one means.
Want a nicer address? cli domains generate shop gives you shop.<app domain>, live at once. See Domains and networking.
6. Add a Postgres database
In the dashboard: choose New service, then Database, pick Postgres and press Create Postgres. Then open the web service, go to Variables, and use Connect a database to give it the database's URL.
From your terminal:
cli add postgresThis creates a private Postgres database and sets DATABASE_URL on the linked service. It also works for mysql, redis and mongo.
Ask your agent:
"Add a Postgres database to my-app and connect it to web."
With the API:
POST /v1/projects/:id/databases{ "kind": "postgres", "linkTo": "svc_web123" }7. Redeploy
The app only sees the new DATABASE_URL after a redeploy. Wait until the database is up, then:
In the dashboard: press Deploy now on the web service.
From your terminal:
cli deployAsk your agent:
"Redeploy web and check it can reach the database."
With the API:
POST /v1/services/:id/deploysThat's it: your app is live with a database, backed up daily.
Next steps
- Set your app's other variables: Variables and configuration.
- Turn on PR previews and safe releases: Previews and safe releases.
- Connect your agent and set its limits: Connect your AI agent and Agent permissions and limits.
- Keep an eye on spending:
cli usageor Credit, pricing and billing.