2020-04-02

Nhost CLI released - feedback wanted!

nunopato's avatar on Twitter
Nuno Pato

At Nhost, our main goal is to enable people to build web/mobile apps faster by providing the infrastructure and configuration needed to be up & running in no time.

After talking to some of our earlier customers, we decided to start working on a CLI that would make it easy to re-create Nhost's backend environment on a local machine. This not only makes it easier for you to test web/mobile products but it also paves the way for new features coming soon (promoting local DB schema changes to other environments, preview environments, and deployment to production on PR merge).

After a couple of iterations, we are releasing a beta version of the CLI that we believe will make your life easier when building projects with Nhost.

The CLI is distributed through npm and can be installed via:

npm install -g nhost

Nhost depends on Hasura's CLI and Docker Compose. Please make sure you have both installed.

Let's now see how one would use the CLI to develop projects with Nhost. There are 2 different scenarios when initialising a project, described bellow:

Initialising a new project from scratch

A new project can be started from scratch with nhost init [-d]. If -d is not specified, the working directory is assumed.

➜ nhost init -d myproject

Nhost boilerplate created within myproject

The init command creates configuration that allows a user to specify what versions to run and in what ports.

cd myproject
➜ la
total 16
12B Apr 14 11:23 .gitignore
527B Apr 14 11:23 config.yaml
96B Apr 14 11:23 migrations
➜ cat config.yaml

# configurations used when starting your environment

# hasura graphql configuration

graphql_version: 'v1.1.0.cli-migrations'
graphql_server_port: 8080
#graphql_admin_secret: (optional: if not specified, it will be generated on 'nhost dev')

# postgres configuration

postgres_version: 12.0
postgres_port: 5432
postgres_user: postgres
postgres_password: postgres
#postgres_db_data: (optional: if not specified, './db_data' will be used)

# hasura backend plus configuration

backend_plus_version: v1.2.3
backend_plus_port: 9000

It is worth mentioning that now, before running nhost dev for the first time, and having a volume for your PostgreSQL data created, it is the best time to change your PostgreSQL user and password if the defaults are not what you want. Note that you can also specify where the DB data goes.

Finally, the migrations folder has one migration for the auth schema, required by the Hasura Backend Plus (HBP) service, and that will be applied when running nhost dev for the first time.

Initialising an existing project

For projects already running on our managed Nhost service that you want to have running locally in your dev environment, init provides 2 additional options, --endpoint and --admin-secret that allows the CLI to create the migration files for your dev environment to match production. These should be used only if you already have a project up & running with Nhost in production.

--endpoint refers to where GraphQL engine is running and --admin-secret specifies the secret used with your API. You can find both of these on your project's page.

➜ nhost init --endpoint=https://hasura-[id].nhost.app --admin-secret=fcc4d1414b4be31a1dd5e682bce

INFO Migrations files created name=init version=1586866698992
Nhost boilerplate created

As the output implies, migration files are created based on your production DB/schema. These migrations will be applied on the first run of nhost dev.

And that's it for initialisation! From now on, when you change your DB/schema while developing locally, new migration files are created in the migrations folder. Very soon, you will be able to push those changes to production.

Starting the local environment

To start your environment, simply issue nhost dev.

➜ nhost dev
development environment is launching...

INFO console running at: http://localhost:9695/

All the necessary schema for managing users and authentication (only the auth schema is shown here) are now in place.

Go ahead and try the following cURL commands:

➜ curl -X POST -H "Content-Type: application/json" --data '{"email": "nuno@nhost.io", "username": "nunopato", "password": "123456" }' http://localhost:9000/auth/local/register

OK
➜ [~/myproject] curl -X POST -H "Content-Type: application/json" --data '{"username": "nunopato", "password": "123456" }' http://localhost:9000/auth/local/login

{"refresh_token":"c6997ce7-cc2e-4bff-b071-b4cfc7d7b7bb","jwt_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL2hhc3VyYS5pby9qd3QvY2xhaW1zIjp7IngtaGFzdXJhLWFsbG93ZWQtcm9sZXMiOlsidXNlciJdLCJ4LWhhc3VyYS1kZWZhdWx0LXJvbGUiOiJ1c2VyIiwieC1oYXN1cmEtdXNlci1pZCI6ImJiNmFiZWQ5LWMyMDgtNDg3NC04OGYxLTJhNTIxOThhNTIwOSIsIngtaGFzdXJhLWlzLWFub255bW91cyI6ImZhbHNlIn0sImlhdCI6MTU4Njg2ODkwMCwiZXhwIjoxNTg2ODY5ODAwfQ.QGpZkZpDMRnP4klkniWIQZLtcHMncYkHtzRDK47Zh8g"}

That's it for now, we hope that you find the CLI easy and convenient to use. Feel free to send us any feedback you might have, or submit any bugs/issues you might find on the project's repository https://github.com/nhost/cli.

We appreciate your time and feedback!

What's next?
Did you find this blog post interesting? Follow me on Twitter where I write more about my journey with Nhost.
Try Nhost for Free Today
Focus on your app and your users!

The Jamstack backend with Hasura.

Product
Build
Coming soon
Resources
Company
© Nhost
githubtwitterdiscordyoutubelinkedin