There are a few things that will make managing your pico engine and writing KRL code easier. 

Managing your Pico Engine

If you need to remove your pico engine and change to a different version, follow these instructions.

Installation

To install and run the pico engine:

$ npm install -g pico-engine
$ pico-engine

Install a Specific Version

Install a specific version of the pico engine code. In this example, the engine as of March 28, 2017 was at version 0.5.13.

npm install -g pico-engine@0.5.13

Update to the Latest Version

You can update to the latest version using the command

npm update -g pico-engine

Check Your Version

You can see which version you are using near the top-left corner of the "My Picos" page (localhost:8080) or by running the command

npm ls -g pico-engine

or

pico-engine --version

Remove Pico Engine

Remove the pico engine code.

npm rm -g pico-engine

Initialize

If you wish to remove all picos and start over, use one or more of these commands.

rm -r ~/.pico-engine/db #removes all picos and cached ruleset source code
rm -r ~/.pico-engine/rulesets #removes compiled ruleset node modules
rm -r ~/.pico-engine #shortcut to do both of the above

Running multiple pico engines

To run multiple pico engines on the same host, you will need to assign each instance of the engine a different port and a different folder for its database and ruleset cache. For example, while running a pico engine listening on the default port, and using the default location for its database, you could start an additional instance with a command like this one:

PORT=8081 
PICO_ENGINE_HOME=~/.pico-engine-1 pico-engine

Running Your Engine In Dev vs Production Mode

There are a few ways to start the pico engine. If you globally installed it, the command is simply "pico-engine". If you cloned the engine from github, then you can use "npm start" from the cloned folder root, or run the cli.js file located in packages/pico-engine/src. The "npm start" command uses a different database than directly running the cli.js file. The "npm start" method creates a database located in packages/pico-engine, whereas the cli.js file creates a database at the location where the pico-engine root folder exists. This second database is under a folder called ".pico-engine". The first method is considered to be a dev mode, whereas the latter is a production mode.

When hosting your engine an a hosting server, like AWS or Digital Ocean, you may use a tool like forever to keep the engine running even when you close your ssh connected terminal. Running the command "npm start" using forever tends to have trouble, and we must run the cli.js file as described above, like this:

forever start packages/pico-engine/src/cli.js

This uses a different database from development mode as described above, so if you need to use the same database for some reason, then you need to specify its location like this:

PICO_ENGINE_HOME=/home/pi/pico-engine/packages/pico-engine forever start /home/pi/pico-engine/packages/pico-engine/src/cli.js

Please note that this absolute path works on a raspberry pi 3, and will likely not be the exact same path if you are running an engine on windows/mac/linux. Try running the engine at least once to create the database, then find the absolute path to use in the forever command.

Hosting Code

Because the rules engine reads your KRL program from the Web, it has to be available online. You can host it anywhere. There are a few options:

1. GitHub works well, with one caveat. See these instructions for more information about how to use GitHub to host KRL. The caveat is that GitHub caches the resources on raw URLs for about 5 minutes. If you're making frequent changes, it can be frustrating to wait out the cache. Alternatively, GitLab should give you fewer caching problems. (raw URLs to rulesets in private repositories need an account access token)
2. AWS S3 works well. Be sure to make the URL for the ruleset is readable by the engine. 

The pico engine compiles your KRL into a Node.js module, which it stores in a folder at ~/.pico-engine/rulesets.

Flushing the Ruleset

Wherever you host your code, the rules engine caches it after parsing it for better performance. That means that you need to flush your code from the rules engine cache whenever you update it. After pushing a change to your ruleset, you will need to instruct the pico engine to retrieve the source code again and re-compile it. Use a URL like this one:

http://localhost:8080/api/ruleset/flush/{rid}

If you wanted to flush a ruleset with RID hello_world. then you'd use this URL to flush that ruleset:

http://localhost:8080/api/ruleset/flush/hello_world

You will need to give the correct domain and port for your pico engine, and mention at the end the RID of your ruleset. In the example above, the RID is hello_world.

You may also flush the ruleset in the UI (as of version 0.7.3 or above), by going to the Engine Rulesets page and clicking on the "flush" link beside the RID of your ruleset.

Parsing KRL

You need to be able to check your ruleset for parse errors before checking it in. Debugging syntax errors on the rules engine is a messy business. 

There are three ways to do it.

1. You can use the "Engine Rulesets" page, hosted by the pico engine at http://localhost:8080/ruleset.html, and copy and paste your KRL ruleset into it. 
2. You can download and run the node pico engine compiler on your own machine and run it from the command line. 
3. You can install a pre-commit hook for git, so that your code is automatically parsed when you commit changes. If your code fails to parse, the change will not be committed.

The second and third methods are recommended for any serious development.

To validate using the first method, open the "Engine Rulesets" page, and paste your entire ruleset into the big text area, and click the "validate" button. When your KRL compiles correctly, you will see a result of "ok" beneath the buttons, with the page looking like this screenshot.