Kaluma CLI

Kaluma CLI is a command-line tool to program devices and boards running Kaluma runtime. It communicates with devices and boards via serial ports. Before using CLI, please ensure that your device or board is connected to a serial port.

• Kaluma CLI
  • Install
  • Recommended Workflow
  • Usage
    • help command
    • ports command
    • flash command
    • erase command
    • shell command
    • bundle command
    • put command
    • get command
  • License

Install

Install CLI via npm globally.

npm install -g @kaluma/cli

If you failed to install, sometime you need to install by building from source as below (e.g. Apple M1, Raspberry Pi, or some Linux).

npm install -g @kaluma/cli --unsafe-perm --build-from-source

You can also install locally and run with npx kaluma.

npm install @kaluma/cli --save-dev

Recommended Workflow

A typical workflow to program Kaluma is:

1. Bundle main (index.js) file. (kaluma bundle ...)
2. Flash the bundled file. (kaluma flash ...)
3. Check errors or outputs in console with shell connection. (kaluma shell ...)

Repeating these tasks is very tedious, so we recommend to use flash command with --bundle and --shell options as below:

kaluma flash index.js --bundle --shell

# shortly
kaluma flash index.js -b -s

It processes all the task sequentially. Lastly you just need to exit the shell connection by pressing ctrl+z.

Usage

help command

Print help for commands and options.

kaluma help [command]

ports command

List all available serial ports.

kaluma ports

flash command

Flash code (.js file) to device.

You can flash only a single .js file to Kaluma. If you have multiple .js files, you need to bundle them with --bundle option or bundle command.

kaluma flash <file> [--port <port>] [--bundle] [--shell] [--no-load] [...]

• <file> : Path to the file to upload.
• -p, --port <port> option : Path to a serial port where device is connected. You can check the available serial ports using ports command. (e.g. /dev/tty* or COM*). Or, you can pass a port query with serial device's VID (Vendor ID) and PID (Product ID) (e.g. @<vid>, @<vid>:<pid>). (Default: @2e8a - This is VID of Respberry Pi, so automatically finds the port of Raspberry Pi Pico if you omit --port option)
• --no-load option : Skip code loading after flash. Use this option if you don't want to run the flashed code immediately.
• -b, --bundle option : Bundle .js code before flash. If you use this option, you can also use all options of bundle command.
• -o, --output <file> option : See bundle command.
• -m, --minify option : See bundle command.
• -c, --sourcemap option : See bundle command.
• -s, --shell option: Flash code with shell connection. With this option you can see all console logs and errors. To exit the shell, press ctrl+z. See shell command.

Examples:

# flash index.js to Raspberry Pi Pico (vid: 2e8a)
kaluma flash index.js

# flash index.js to port: /dev/tty.usbmodem1441
kaluma flash index.js --port /dev/tty.usbmodem1441

# flash index.js without load
kaluma flash index.js --no-load

# bundle index.js and then flash
kaluma flash index.js --bundle

# bundle and flash index.js with shell connection
kaluma flash index.js --shell --bundle

erase command

Erase code in device.

kaluma erase [--port <port>]

• -p, --port <port> option: See flash command.

Example:

# erase code in flash of Raspberry Pi Pico (vid: 2e8a)
kaluma erase

# erase code in flash of port: /dev/tty.usbmodem1441
kaluma erase --port /dev/tty.usbmodem1441

shell command

THIS IS EXPERIMENTAL FEATURE

Shell connect (binds standard I/O to serial port).

kaluma shell [--port <port>]

• -p, --port <port> option: See flash command.

Example:

# shell connect to Raspberry Pi Pico (vid: 2e8a)
kaluma shell

# shell connect to the port: /dev/tty.usbmodem1441
kaluma shell --port /dev/tty.usbmodem1441

bundle command

Bundle codes with webpack.

Note that you can bundle and flash at once with --bundle option of flash command.

kaluma bundle <file> [--output <file>] [--minify] [--sourcemap]

• <file> : Path to the file to bundle.
• -o, --output <file> option : Output path of bundled code. (Default: bundle.js).
• -m, --minify option : Minify the bundled code. It can reduce the code size, but it may harden to debug.
• -c, --sourcemap option : Generates source-map file.

Example:

# Bundle 'index.js' into 'bundle.js'
kaluma bundle index.js

# Bundle 'index.js' into './dist/out.js'
kaluma bundle index.js --output ./dist/out.js

# Bundle 'index.js' into minified 'bundle.js'
kaluma bundle index.js --minify

# Bundle 'index.js' into 'bundle.js' with source-map file 'bundle.js.map'.
kaluma bundle index.js --sourcemap

put command

Copy a file from host computer to device.

kaluma put <src> <dest> [--port <port>]

• <src> Path to a file to send in host computer.
• <dest> Path to the file received in device. Absolute file path is required.
• -p, --port <port> option: See flash command.

Examples:

# copy 'host.txt' [host] to '/dir/device.txt' [Raspberry Pi Pico]
kaluma put host.txt /dir/device.txt

# copy 'host.txt' [host] to '/dir/device.txt' [device]
kaluma put host.txt /dir/device.txt --port /dev/tty.usbmodem1441

get command

Copy a file from device to host computer.

kaluma get <src> <dest> [--port <port>]

• <src> Path to a file in device. Absolute file path is required.
• <dest> Path to the file received in host computer.
• -p, --port <port> option: See flash command.

Examples:

# copy '/dir/device.txt` [Raspberry Pi Pico] to 'host.txt' [host]
kaluma get /dir/device.txt host.txt

# copy '/dir/device.txt` [device] to 'host.txt' [host]
kaluma get /dir/device.txt host.txt --port /dev/tty.usbmodem1441

License

Apache