Nhost CLI Reference
The nhost CLI is the primary tool for developing, deploying, and managing Nhost projects. It lets you run your backend locally, manage configuration and infrastructure as code, link and deploy projects to Nhost Cloud, and provide AI assistants with access to your project through the built-in MCP server.
New here? Head over to Quickstart for CLI installation.
nhost [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]Global Options
Section titled “Global Options”--branch="" | Git branch name. If not set, it will be detected from the current git repository. This flag is used to dynamically create docker volumes for each branch. If you want to have a static volume name or if you are not using git, set this flag to a static value. Default: <current-git-branch>. Env: $BRANCH. |
--dot-nhost-folder="" | Path to .nhost folder. Default: ".nhost". Env: $NHOST_DOT_NHOST_FOLDER. |
--help, -h | show help. |
--local-subdomain="" | Local subdomain to reach the development environment. Default: "local". Env: $NHOST_LOCAL_SUBDOMAIN. |
--nhost-folder="" | Path to nhost folder. Default: "nhost". Env: $NHOST_NHOST_FOLDER. |
--project-name="" | Project name. Default: <project-directory-name>. Env: $NHOST_PROJECT_NAME. |
--root-folder="" | Root folder of project. Default: ".". Env: $NHOST_ROOT_FOLDER. |
--version, -v | print the version. |
Commands
Section titled “Commands”config
Section titled “config”nhost config default
Section titled “nhost config default”Create default configuration and secrets.
nhost config example
Section titled “nhost config example”Shows an example config file.
nhost config apply
Section titled “nhost config apply”Apply configuration to cloud project.
--subdomain="" | Subdomain of the Nhost project to apply configuration to. Defaults to linked project. Env: $NHOST_SUBDOMAIN. |
--yes | Skip confirmation. Env: $NHOST_YES. |
nhost config pull
Section titled “nhost config pull”Get cloud configuration.
--subdomain="" | Pull this subdomain’s configuration. Defaults to linked project. Env: $NHOST_SUBDOMAIN. |
--yes | Skip confirmation. Env: $NHOST_YES. |
nhost config show
Section titled “nhost config show”Shows configuration after resolving secrets.
--subdomain="" | Show this subdomain’s rendered configuration. Defaults to base configuration. Env: $NHOST_SUBDOMAIN. |
nhost config validate
Section titled “nhost config validate”Validate configuration.
--subdomain="" | Validate this subdomain’s configuration. Defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost config edit
Section titled “nhost config edit”Edit base configuration or an overlay.
--editor="" | Editor to use. Default: "vim". Env: $EDITOR. |
--subdomain="" | If specified, edit this subdomain’s overlay, otherwise edit base configuration. Env: $NHOST_SUBDOMAIN. |
deployments
Section titled “deployments”nhost deployments list
Section titled “nhost deployments list”List deployments in the cloud environment.
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost deployments logs
Section titled “nhost deployments logs”View deployments logs in the cloud environment.
--follow | Specify if the logs should be streamed. |
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
--timeout="" | Specify the timeout for streaming logs. Default: 5m0s. |
Experimental
Section titled “nhost deployments new”
nhost deployments new
Section titled “nhost deployments new”Create a new deployment.
--follow | Specify if the logs should be streamed. If set, the command will wait for the deployment to finish and stream the logs. If the deployment fails the command will return an error. |
--message="" | Commit message. |
--ref="" | Git reference. Env: $GITHUB_SHA. |
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
--timeout="" | Specify the timeout for streaming logs. Default: 5m0s. |
--user-avatar-url="" | Commit user avatar URL. |
--user="" | Commit user name. Env: $GITHUB_ACTOR. |
nhost dev compose
Section titled “nhost dev compose”docker compose wrapper, sets project name and compose file automatically.
nhost dev hasura
Section titled “nhost dev hasura”hasura-cli wrapper.
nhost up
Section titled “nhost up”Start local development environment.
--apply-seeds | Apply seeds. If the .nhost folder does not exist, seeds will be applied regardless of this flag. Env: $NHOST_APPLY_SEEDS. |
--auth-port="" | If specified, expose auth on this port. Not recommended. Default: 0. |
--ca-certificates="" | Mounts and overrides path to CA certificates in the containers. Env: $NHOST_CA_CERTIFICATES. |
--dashboard-version="" | Dashboard version to use. Default: "nhost/dashboard:3.0.0". Env: $NHOST_DASHBOARD_VERSION. |
--disable-tls | Disable TLS. Env: $NHOST_DISABLE_TLS. |
--down-on-error | Skip confirmation. Env: $NHOST_YES. |
--functions-port="" | If specified, expose functions on this port. Not recommended. Default: 0. |
--functions-version="" | Functions version to use. Default: "2.1.0". Env: $NHOST_FUNCTIONS_VERSION. |
--hasura-console-port="" | If specified, expose hasura console on this port. Not recommended. Default: 0. |
--hasura-port="" | If specified, expose hasura on this port. Not recommended. Default: 0. |
--http-port="" | HTTP port to listen on. Default: 443. Env: $NHOST_HTTP_PORT. |
--postgres-port="" | Postgres port to listen on. Default: 5432. Env: $NHOST_POSTGRES_PORT. |
--run-service-volume="" | Mount a local directory into a run service container. Format: service-name=/local/path:/container/path. Can be passed multiple times. Env: $NHOST_RUN_SERVICE_VOLUME. |
--run-service="" | Run service to add to the development environment. Can be passed multiple times. Comma-separated values are also accepted. Format: /path/to/run-service.toml[:overlay_name]. Env: $NHOST_RUN_SERVICE. |
--storage-port="" | If specified, expose storage on this port. Not recommended. Default: 0. |
Beta
Section titled “nhost up cloud”
nhost up cloud
Section titled “nhost up cloud”Start local development environment connected to an Nhost Cloud project.
--apply-seeds | Apply seeds. If the .nhost folder does not exist, seeds will be applied regardless of this flag. Env: $NHOST_APPLY_SEEDS. |
--ca-certificates="" | Mounts and overrides path to CA certificates in the containers. Env: $NHOST_CA_CERTIFICATES. |
--dashboard-version="" | Dashboard version to use. Default: "nhost/dashboard:3.0.0". Env: $NHOST_DASHBOARD_VERSION. |
--disable-tls | Disable TLS. Env: $NHOST_DISABLE_TLS. |
--down-on-error | Skip confirmation. Env: $NHOST_YES. |
--hasura-console-port="" | If specified, expose hasura console on this port. Not recommended. Default: 0. |
--http-port="" | HTTP port to listen on. Default: 443. Env: $NHOST_HTTP_PORT. |
--postgres-url="" | Postgres URL. Env: $NHOST_POSTGRES_URL. |
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost down
Section titled “nhost down”Stop local development environment.
--volumes | Remove volumes. |
nhost logs
Section titled “nhost logs”Show logs from local development environment.
docker-credentials
Section titled “docker-credentials”nhost docker-credentials configure
Section titled “nhost docker-credentials configure”Install credentials helper and configure docker so it can authenticate with Nhost’s registry.
--docker-config="" | Path to docker config file. Default: $HOME/.docker/config.json. Env: $DOCKER_CONFIG. |
--no-interactive | Do not prompt for confirmation. Env: $NO_INTERACTIVE. |
nhost mcp config
Section titled “nhost mcp config”Generate and save configuration file.
--confirm | Skip confirmation prompt. Env: $CONFIRM. |
nhost mcp config dump
Section titled “nhost mcp config dump”Dump the configuration to stdout for verification.
nhost mcp start
Section titled “nhost mcp start”Starts the MCP server.
nhost mcp gen
Section titled “nhost mcp gen”Generate GraphQL schema for Nhost Cloud.
--with-mutations | Include mutations in the generated schema. Env: $WITH_MUTATIONS. |
nhost init
Section titled “nhost init”Initialize a new Nhost project.
--remote | Initialize pulling configuration, migrations and metadata from the linked project. Env: $NHOST_REMOTE. |
nhost list
Section titled “nhost list”List remote apps.
nhost link
Section titled “nhost link”Link local app to a remote one.
nhost docs list
Section titled “nhost docs list”List all documentation pages. Aliases: ls
--grouped | Show pages organized by section. |
--summary | Show page descriptions. |
nhost docs search
Section titled “nhost docs search”Search documentation pages. Aliases: s, find
--limit, -n="" | Maximum number of results to return. Default: 5. |
nhost docs show
Section titled “nhost docs show”Display contents of a documentation page. Aliases: view
--raw | Show raw MDX content including frontmatter. |
nhost run config-show
Section titled “nhost run config-show”Shows Run service configuration after resolving secrets.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--overlay-name="" | If specified, apply this overlay. Env: $NHOST_RUN_SERVICE_ID, $NHOST_SERVICE_OVERLAY_NAME. |
nhost run config-deploy
Section titled “nhost run config-deploy”Deploy service configuration.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--service-id="" | Service ID to update. Applies overlay of the same name. Env: $NHOST_RUN_SERVICE_ID. |
nhost run config-edit
Section titled “nhost run config-edit”Edit service configuration.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--editor="" | Editor to use. Default: "vim". Env: $EDITOR. |
--overlay-name="" | If specified, apply this overlay. Env: $NHOST_RUN_SERVICE_ID, $NHOST_SERVICE_OVERLAY_NAME. |
nhost run config-edit-image
Section titled “nhost run config-edit-image”Edits configuration file and sets the image.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--image="" | Image to use. Env: $NHOST_RUN_SERVICE_IMAGE. |
nhost run config-pull
Section titled “nhost run config-pull”Download service configuration.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--service-id="" | Service ID to update. Env: $NHOST_RUN_SERVICE_ID. |
nhost run config-validate
Section titled “nhost run config-validate”Validates service configuration after resolving secrets.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--overlay-name="" | If specified, apply this overlay. Env: $NHOST_SERVICE_OVERLAY_NAME. |
--service-id="" | If specified, apply this overlay and remote secrets for this service. Env: $NHOST_RUN_SERVICE_ID. |
nhost run config-example
Section titled “nhost run config-example”Shows an example config file.
nhost run env
Section titled “nhost run env”Outputs environment variables. Useful to generate .env files.
--config="" | Service configuration file. Default: "nhost-run-service.toml". Env: $NHOST_RUN_SERVICE_CONFIG. |
--overlay-name="" | If specified, apply this overlay. Env: $NHOST_RUN_SERVICE_ID, $NHOST_SERVICE_OVERLAY_NAME. |
--prepend-export | Prepend ‘export’ to each line. Env: $NHOST_RuN_SERVICE_ENV_PREPEND_EXPORT. |
schema
Section titled “schema”nhost schema diff
Section titled “nhost schema diff”Compare two GraphQL schema files.
--no-clean | Disable all normalization/cleaning of known-safe differences. |
-a="" | Path to the first schema file. |
-b="" | Path to the second schema file. |
nhost schema dump
Section titled “nhost schema dump”Dump a GraphQL schema as SDL.
--admin-secret="" | Admin secret (defaults: local subdomain → nhost-admin-secret; cloud → fetched from Nhost API). NHOST_ADMIN_SECRET is consulted only when —url is not set and never forwarded to —url. |
--header, -H="" | Extra HTTP header to send, repeatable (e.g. “X-Hasura-Foo: bar”). |
--metadata, -m="" | Path to a Hasura metadata directory to generate the schema from. |
--output, -o="" | Output file (default: stdout). |
--role, -r="" | Role to generate the schema for. Metadata mode defaults to “user”; URL mode sends X-Hasura-Role only when this flag is explicitly set. Default: "user". |
--subdomain="" | Project subdomain (defaults to the linked project; use ‘local’ for the local dev stack). Env: $NHOST_SUBDOMAIN. |
--timeout="" | HTTP timeout in seconds (URL mode only). Default: 30. |
--url, -u="" | GraphQL endpoint URL to introspect. |
secrets
Section titled “secrets”nhost secrets create
Section titled “nhost secrets create”Create secret in the cloud environment.
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost secrets delete
Section titled “nhost secrets delete”Delete secret in the cloud environment.
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost secrets list
Section titled “nhost secrets list”List secrets in the cloud environment.
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost secrets update
Section titled “nhost secrets update”Update secret in the cloud environment.
--subdomain="" | Project’s subdomain to operate on, defaults to linked project. Env: $NHOST_SUBDOMAIN. |
nhost sw uninstall
Section titled “nhost sw uninstall”Remove the installed CLI from system permanently.
--force | Force uninstall without confirmation. Env: $NHOST_FORCE_UNINSTALL. |
nhost sw upgrade
Section titled “nhost sw upgrade”Upgrade the CLI to the latest version.
nhost sw version
Section titled “nhost sw version”Show the current version of Nhost CLI you have installed.
nhost login
Section titled “nhost login”Login to Nhost.
gen-docs
Section titled “gen-docs”nhost gen-docs
Section titled “nhost gen-docs”Generate markdown documentation for the CLI.