nstack CLI

The nstack CLI is used to build modules and workflows on a linked NStack server. It can be configured via the nstack.conf yaml file found in ~\.config on Linux/macOS, and in HOME/AppUser/Roaming on Windows, or indirectly via the nstack set-server command described below.


Having installed the CLI, make sure it’s accessible from your path

$ nstack --version
> nstack 0.0.3

You can find the list of commands and options available by running

$ nstack --help


This section explains the commands supported by the CLI toolkit.


$ nstack register username email [-s SERVER]
Option Description
username A unique username to assign on the the server.
email An email address to validate the user and send login credentials to.
SERVER The remote NStack Server to register with, by default this will use our demo server.

A simple command to register with a remote NStack server so you can login, build modules, start workflows, etc. Upon successful registration you will receive credentials over email that you can paste into the nstack CLI and get started.


$ nstack set-server server-addr server-port id key

This command configures your local NStack CLI to communicate with a remote NStack Server with which you have registered (see previous command). You usually don’t have to enter this command by hand, it will be contained with an email after successful registration that you can paste directly into your terminal.

Internally this modifies the nstack.conf CLI config file on your behalf (found in ~\.config on Linux/macOS, and in HOME/AppUser/Roaming on Windows).


$ nstack info

Displays information regarding the entire current state of NStack, including:

  • Modules
  • Sources
  • Sinks
  • Running processes
  • Base images


$ nstack init <stack>
Option Description
stack The default stack to use to build your service, e.g. python or workflow (.nml NStack Workflow Language).

Initialises a new nstack module in the current directory using the specified base language stack. This creates a working skeleton project which you can use to write your module.

If you are creating a module in an existing programming language, such as Python, init creates a module with a single numChars function already created. The initial project is comprised of the following files,

  • nstack.yaml, your service’s configuration file (see module_structure),
  • service.py, an application file (or service.js, etc.), where your business-logic lives
  • an empty packages file (e.g. requirements.txt for Python, or package.json for Node, etc.).

init is the command used to create a new workflow. In this case, NStack creates a skeleton module.nml file.


$ nstack build

Builds a module or project (see features-python) on your hosted nstack instance.


build is also used to build workflows. Remember, workflows are modules too!


$ nstack start <module_name> <function_name>
Option Description
module_name The nstack module which contains a fully-composed workflow function
function_name The fully-composed workflow function name

Used to start a workflow as a process. For example,

$ nstack start MyWorkflow:0.0.1 myWorkflow


$ nstack notebook

Create an interactive session within the terminal that provides a mini-REPL (you can also redirect a file/stream into the notebook command to provide for rapid service testing and development).

From this command-line, you can import modules as needed, and enter a single workflow that will be compiled and run immediately on the server (press <Ctrl-D> on Linux/macOS or <Ctrl-Z> on Windows to submit your input).

$ nstack notebook
import Demo.Classify:0.0.3 as D;
Sources.http<Text> { http_path = "/classify" } | D.numChars | Sinks.log<Text>
> Service started successfully as process 5


$ nstack send "route" 'data'
Option Description
route The endpoint to send the data where a workflow is running.
data A json snippet to send to the endpoint and pass into a workflow.

Used with the HTTP source, nstack send sends a JSON-encoded element to an endpoint on the NStack server where a workflow has been started. Useful for testing workflows that are to be used as web-hooks.


$ nstack test <function> <input>
Option Description
module A fully-qualified module name, e.g. Foo:0.0.1
function A function in the given module, e.g. numChars
input A json snippet declaring test input to the function

Used to test a function by sending it a single piece of input data, and logging the results. The function will be started, called with the test data to process, and then stopped.

Test is equivalent to starting the function with an HTTP source and log sink, using nstack send to send an input value, and then stopping the process.

It can be used for unit-testing a function and ensuring the module code works correctly.

The test data should be JSON-encoded, just as with nstack send. The test data must be of the type the function expects or it will be rejected by the nstack server.

$ nstack test Foo:0.0.1 numChars '"Hello World"'

$ nstack test Foo:0.0.1 sum '[1,2,3]'


$ nstack ps

Shows a list of all processes, which are workflows that are running on your your nstack server.


$ nstack stop <process-id>

Stop a running process.


$ nstack list <primitive>
Option Description
<primitive> The primitive you want to list.

Shows a list of available primitives. Support primitives are modules, workflows, functions, sources, and sinks.


$ nstack delete <module>

Deletes a module (and thus its functions) from NStack.


$ nstack log <process>
Option Description
<process> The id of the process.

View the logs of a running process.


$ nstack server-logs

View the full logs of the NStack server.


$ nstack gc

Expert: Garbage-collect unused module images to free up space on the server.