# CLI Tool

The Nodewood CLI Tool is designed to be installed globally to help you develop inside your Nodewood project:

yarn global add @nodewood/cli

# Creating a new project

To create a new Nodewood project, consult the Create a project section of the Installation page of the documentation.

# Connecting to the Nodewood development VM

Nodewood uses Vagrant and VirtualBox to launch an instance of Ubuntu, and then Ansible to configure it. While you will probably want to learn about those tools in their own right, you don't need to really know more than that to get started.

Once you have a Nodewood project created, change to the root directory and then run:

nodewood vm

This will launch the VM if it is not yet running, then connect to it. Once connected, your project's code is shared in the ~/code folder. Any changes you make to your host system's code will immediately be reflected there.

# Running/Rolling back migrations

While Nodewood uses MassiveJS for database access, it doesn't come with a built-in migrations library. So for this purpose, we use the excellent migrations capabilities of Knex.JS. To run existing migrations, run:

nodewood migrate

This will run all migrations from the app/migrations and wood/migrations folders. You can optionally add test to the end of the command (nodewood migrate test) to run migrations against the test database.

To rollback the most-recent set of changes, run:

nodewood rollback

Again, you can add test to the end of the command (nodewood rollback test) to rollback the most recent set of changes from the test database.

This should handle the vast majority of cases you'll encounter for migrations, but should you require anything more complex, you should consult the Knex.JS migrations documentation.

# Starting the Nodewood development server/watchers

Once connected to the VM and in the ~/code directory, you can start the development Express server with:

nodewood dev api

This will begin serving your application from the VM's IP address (defaults to 192.168.33.13). It is recommended that you add that IP address to your hosts file to make it easy to connect, but you can always just visit https://192.168.33.13 in your browser to start.

Any API code you alter will trigger a reload of the Express server, so you may have to wait a second or two in between making changes and testing.

If you are going to be making changes to your UI code as well, you'll want to start the UI development watcher. In another window, connect to the VM, change to the ~/code directory, and run:

nodewood dev ui

This will build the UI and start a watcher that works much the same way the API watcher works - when you change UI code, it will rebuild the UI. It also can take a few seconds in between making changes and finishing the rebuild.

# Watching UI locally

You don't necessarily have to run the UI watcher on the VM - it's just already configured for you to do so. Since the UI doesn't rely on connecting to the database on the VM, you can run it locally to reduce the average build time when making changes.

A caution about building locally - do not run yarn install locally unless you are using the same OS as the development VM (Ubuntu), as certain shared libraries may install binary code that is not compatible between OSes. Always run yarn install from the development VM. If you do accidentally run yarn install from your host OS, all is not lost. Simply run rm -rf node_modules from the root of your Nodewood project, then run yarn install from the development VM.

# Adding new files to your project from a template

You can always add a new file to your project by creating a blank file in the correct location, but if you want a template to start from, you can use the nodewood add command.

For more information on how this command works, refer to the documentation on the different file types, as they will have detailed information on how to add templates there.

# Upgrading your Nodewood installation

To upgrade your Nodewood installation, run:

nodewood up

This will first check what upgrade version your license gives you access to, present the migration notes for all versions between yours and that version, and confirm that you wish to upgrade. Then, it will replace the contents of the wood folder in your project with the upgraded contents.

For this reason, it is strongly recommended to never change the contents of the wood folder, as it could be removed at any point.