Skip to content
Nhost Documentation
SupportDashboard

Get up and running with the Nhost CLI

Start developing locally with Nhost. Install the CLI, initialize your project, and spin up a local PostgreSQL database, GraphQL engine, Auth, and Storage.

CLI quickstart local development Nhost CLI setup install

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

Docker is required to run the local environment.

1. Install the CLI

Section titled “1. Install the CLI”

Supported platforms

  • macOS
  • Linux
  • Windows (via WSL2)1

Choose your preferred installation method:

npm install -g @nhost/cli

Or run the CLI without installation:

npx @nhost/cli@latest --version

2. Authenticate

Section titled “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

3. Initialize a Project

Section titled “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

Section titled “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

Section titled “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.

Nhost local dashboard

6. Connect an AI Assistant (optional)

Section titled “6. Connect an AI Assistant (optional)”

The CLI ships an MCP server that lets an AI assistant read your GraphQL schema, run queries and mutations, and manage metadata and migrations against your local project. The fastest way to set it up is to hand the onboarding file to your assistant:

curl -fsSL https://docs.nhost.io/install-mcp | claude

See MCP Development Setup for the manual steps and client configuration.

Next Steps

Section titled “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

MCP Server

Connect an AI assistant to your local project