Get started with Nhost CLI
Nhost's command-line interface (CLI) lets you run a complete Nhost development environment locally with the following services: PostgreSQL database, Hasura, Authentication, Storage (MinIO), Serverless Functions, and Emails (Mailhog).
Installation
Install the binary globally
To install Nhost CLI, run this command from any directory in your terminal:
sudo curl -L https://raw.githubusercontent.com/nhost/cli/main/get.sh | bash
On MacOS and Linux, this will install the Nhost CLI in /usr/local/bin
.
If you'd prefer to install to a different location other than /usr/local/bin
,
set the INSTALL_PATH
variable accordingly:
sudo curl -L https://raw.githubusercontent.com/nhost/cli/main/get.sh | INSTALL_PATH=$HOME/bin bash
On Windows, this will download and extract the binary nhost.exe
available
under Assets
of the latest release from the GitHub release page:
https://github.com/nhost/cli/releases.
You can move the executable to a different location and add the path to the
environment variable PATH
to make nhost
accessible globally.
Finally, you can check that everything has been successfully installed by typing:
nhost version
(Optional) Add shell completion
To add command auto-completion in the shell, you can run the following command:
nhost completion [shell]
This will generate the autocompletion script for nhost
for the specified shell
(bash, fish, PowerShell, or zsh).
Prerequisites
Dependencies
Before using the Nhost CLI, make sure you have the following dependencies installed on your local machine:
caution
Docker must be running while using Nhost CLI.
Nhost CLI login
After installing Nhost CLI, you can log in to your Nhost account by running the following command:
nhost login
This will display a prompt for you to enter your Nhost account credentials (email/password).
info
You can create a Nhost account here: https://app.nhost.io.
After successfully logging in, you are authorized to manage your Nhost projects using the Nhost CLI.
You can also log out at any time by running:
nhost logout
Set up your project
1. Create a new Nhost project
First things first, we need to create a new Nhost project.
So, log in to your Nhost dashboard and click the Create Your First Project button.
Next, give your new Nhost project a name, select a geographic region for your Nhost services and click Create Project.
After a few seconds, you should get a PostgreSQL database, a GraphQL API with Hasura, file storage, and authentication set up.
2. Create a new GitHub Repository
A typical workflow would also include creating a Github repository for your Nhost project. It will facilitate your development workflow since Nhost can integrate with Github to enable continuous deployment.
So, go to your Github account and create a new repository. You can make your repository either public or private.
3. Connect Nhost project to Github
Finally, connect your GitHub repository to your Nhost project. Doing so will enable Nhost to deploy new versions of your project when you push new commits to your connected Git repository.
- From your project workspace, click Connect to GitHub.
- Install the Nhost app on your GitHub account.
- Connect your GitHub repository.
Develop locally
1. Initialize your Nhost project
Nhost CLI brings the functionality of your Nhost production environment directly to your local machine.
It provides Docker containers to run the backend services that match your production environment in a local environment. That way, you can make changes and test your code locally before deploying those changes to production.
Initialize your Nhost project locally with the following command:
nhost init --remote
It will prompt you to choose what Nhost project you want to initialize.
Your file system will be populated with the following files and folders:
my-nhost-app/
└─ nhost/
├─ config.yaml
├─ emails/
├─ metadata/
├─ migrations/
└─ seeds/
Finally, make sure to link your current working directory to your GitHub repository:
echo "# my-nhost-app" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/[github-username]/my-nhost-app.git
git push -u origin main
2. Start a local development environment
To start a local development environment for your Nhost project, run the following command:
nhost up
caution
Make sure Docker is up and running. It’s required for Nhost to work.
Running this command will start up all the backend services provided by Nhost.
It also runs a webserver to serve the Hasura Console for the GraphQL Engine so you can manage the database and test the GraphQL API.
The Hasura Console opens automatically at http://localhost:1337.
3. Make changes
There are three things the Nhost CLI and the GitHub integration track and apply to production:
- Database Migrations
- Hasura Metadata
- Serverless Functions
caution
Settings in nhost/config.yaml
are not being applied to production. They only work locally for now.
Database migrations
Database changes are tracked and managed through migrations.
tip
You must use the Hasura Console to make database changes. With the Hasura Console, database migration files are automatically generated incrementally to track database changes for you.
To demonstrate how to make database changes, let's create a new table called
messages
, with the following columns:
id
(type UUID and defaultgen_random_uuid()
),text
(type Text),authorId
(type UUID),createdAt
(type Timestamp and defaultnow()
)
In the Hasura Console, go to the DATA tab section and click on the PostgreSQL database (from the left side navigation) that Nhost provides us.
Click on the public schema and then the Create Table button.
Enter the values for creating the messages
table as mentioned above.
Also, specify the id
column as the primary key of the table, and link the
authorId
column to the users.id
column using a foreign key to link the
users
and messages
tables together.
Next, click on the Add Table button to create the table.
Finally, check out the migrations/
folder in your project directory. A
migration file has been created automatically to reflect our database changes
and track the new table creation.
The migration was created under nhost/migrations/default
:
$ ls -la nhost/migrations/default
total 0
drwxr-xr-x 3 user staff 96 Apr 27 17:06 .
drwxr-xr-x 3 user staff 96 Apr 27 17:06 ..
drwxr-xr-x 4 user staff 128 Apr 27 17:06 1651071963431_create_table_public_messages
Note that this database migration has only been applied locally. In
other words, the messages
table does not (yet) exists in production.
To apply the local changes to production, check out the Deploy your project section below.
Hasura metadata
In addition to database schema changes, Nhost also tracks Hasura metadata.
The Hasura metadata track all the actions performed on the console, like tracking tables/views/functions, creating relationships, configuring permissions, creating event triggers, and remote schemas.
To demonstrate it, let's add a new permission to our messages
table for the
user
role on the insert
operation. That permission will allow users to
create new messages.
So, open the permissions tab for the messages
table, type in user
in the
role cell, and click the edit icon on the insert
operation:
To restrict the users to create new messages only for themselves, specify an
_eq
condition between the authorId
and the X-Hasura-User-ID
session
variable, which is passed with each request.
Then, select the columns the users can define through the GraphQL API, set the
value for the authorId
column to be equal to the X-Hasura-User-ID
session
variable, and click Save Permissions.
Finally, check out the metadata/
folder in your project directory to confirm
that the permission changes we did were tracked locally in your git repository.
In our case, those changes should be tracked in
nhost/metadata/databases/default/tables/public_messages.yaml
:
table:
name: messages
schema: public
insert_permissions:
- permission:
backend_only: false
check:
authorId:
_eq: X-Hasura-User-Id
columns:
- text
set:
authorId: x-hasura-User-Id
role: user
Serverless Functions
Now let's create a Serverless Function before we push all changes to GitHub so Nhost can deploy them to production.
For this guide, let's create a Serverless Function that will return the current date-time when called.
First, make sure to install express
, which is required for serverless
functions to work.
npm install express
npm install -d @types/node @types/express
Then, create a new file named time.ts
inside the functions/
folder of your
working directory, and paste the following code:
import { Request, Response } from 'express'
export default (req: Request, res: Response) => {
return res.status(200).send(`Hello ${req.query.name}! It's now: ${new Date().toUTCString()}`)
}
Every JavaScript and TypeScript file inside the functions/
folder becomes an
API endpoint.
Locally, the base URL for the serverless functions is
http://localhost:1337/v1/functions
. Then, the endpoint for each function is
determined by its filename or the name of its dedicated parent directory.
For example, the endpoint for our function is
http://localhost:1337/v1/functions/time
.
curl http://localhost:1337/v1/functions/time\?name\=Greg
Hello Greg! It's now: Wed, 27 Apr 2022 18:52:12 GMT
Deploy your project
To deploy your local changes to production, you can commit and push them to GitHub. As a result, Nhost will automatically pick up the changes in your repository and apply them to your associated remote Nhost project.
caution
Make sure to connect your Github repository to your Nhost project first.
git add -A
git commit -m "commit message"
git push
To check out your deployment, head over to the Deployments tab in your Nhost dashboard.
Get help
To get usage tips and learn more about available commands from within Nhost CLI, run the following:
nhost help
For more information about a specific command, run the command with the --help
flag:
nhost init --help
If you have additional questions or ideas for new features, you can start an issue or a new discussion on Nhost CLI’s open-source repository. You can also chat with our team on Discord.
We’d love to hear from you!