Get up and running with the Nhost CLI

The Nhost CLI is the recommended way to start building your application. It sets up a full local development environment including PostgreSQL, Hasura (GraphQL), Authentication, and Storage, tracking all migrations and metadata.

Docker is required to run the local environment.

1. Install the CLI

Supported platforms

• macOS
• Linux
• Windows (via WSL2)¹

Caution

¹ Windows isn’t supported natively. WSL2 is required to install and use the Nhost CLI. We recommend using docker-ce inside WSL2 instead of Docker Desktop.

Choose your preferred installation method:

npm

npm install -D @nhost/cli

pnpm

pnpm add -D @nhost/cli

Yarn

yarn add -D @nhost/cli

Bun

bun add -d @nhost/cli

Homebrew

brew install nhost/tap/nhost

cURL script

curl -sSL https://raw.githubusercontent.com/nhost/nhost/main/cli/get.sh | bash

Nix

nix profile install github:nhost/nhost#cli

You can also run the CLI without installing it:

npm

npx @nhost/cli@latest --version

pnpm

pnpm dlx @nhost/cli@latest --version

Yarn

yarn dlx @nhost/cli@latest --version

Bun

bunx @nhost/cli@latest --version

2. Authenticate

Login to your Nhost account. This is required if you want to pull configuration from an existing Nhost Cloud project (step 3) or deploy later. You can skip it if you only want to develop locally.

nhost login

Note

If you registered with GitHub, set a password on your account page first.

3. Initialize a Project

Initialize a new Nhost project in your current directory.

nhost init

This scaffolds your project — a nhost/ directory holding your backend configuration (all version-controlled in Git) plus a functions/ directory for serverless functions:

.
├─ 📁 functions       # Serverless functions (Node.js / TypeScript)
└─ 📁 nhost           # Project & backend configuration
    ├─ 📁 emails      # Email templates (verification, password reset, …)
    ├─ 📁 metadata    # Hasura metadata — tables, permissions, relationships
    ├─ 📁 migrations  # Database schema migrations
    └─ 📁 seeds       # Seed data for local development

If you already have a project on Nhost Cloud and want to pull down its configuration:

nhost init --remote

4. Start Local Environment

Start the full Nhost stack locally. This uses Docker to spin up all the necessary services.

nhost up

Once running, the CLI prints the URLs for your local services:

---

Service	URLs
Postgres:	postgres://postgres:postgres@localhost:5432/local
Hasura:	https://local.hasura.local.nhost.run
GraphQL:	https://local.graphql.local.nhost.run
Auth:	https://local.auth.local.nhost.run
Storage:	https://local.storage.local.nhost.run
Functions:	https://local.functions.local.nhost.run
Dashboard:	https://local.dashboard.local.nhost.run
Mailhog:	https://local.mailhog.local.nhost.run

The local.nhost.run domain resolves to your machine, so these URLs work over HTTPS out of the box.

To stop the environment run nhost down, and to follow the logs run nhost logs.

5. Open the Dashboard

Open the local dashboard by going to https://local.dashboard.local.nhost.run to manage your database, auth settings, storage, and more.

Next Steps

Now that your local backend is running, you can connect your frontend application to it or dive deeper into the CLI.

Next.js

Connect your local Nhost backend to a Next.js app

React

Connect your local Nhost backend to a React app

CLI Reference

Full reference for all CLI commands and flags

Local Development

Go deeper: database migrations, metadata, and deploying to Nhost