CLI Reference

Complete reference for the shurikenctl command-line interface.

Installation

See Installation Guide for setup instructions.

Global Options

shurikenctl [OPTIONS] [COMMAND]

Options:
  --version     Show version information
  --help        Display help message

Commands

list

List installed shurikens and their states.

shurikenctl list [OPTIONS]

# Show all shurikens
shurikenctl list

# Show with detailed state
shurikenctl list --state

Output:

example-service    (Running)
webserver          (Idle)
database           (Running)

install

Install a .shuriken package.

shurikenctl install <PATH>

# Examples
shurikenctl install ./service.shuriken
shurikenctl install ~/Downloads/com.example.app-linux-x86_64.shuriken

Process:

Validates magic bytes and metadata
Verifies SHA-256 signature
Extracts to ~/.ninja/shurikens/{name}/
Runs post-install script if specified

remove

Uninstall a shuriken.

shurikenctl remove <NAME>

# Example
shurikenctl remove example-service

Warning: This deletes all shuriken files. Backup data first if needed.

start

Start a shuriken service.

shurikenctl start <NAME>

# Example
shurikenctl start webserver

Behavior:

Native: Spawns process and creates lock file
Script: Executes start() function in management script

stop

Stop a running shuriken.

shurikenctl stop <NAME>

# Example
shurikenctl stop webserver

Behavior:

Native: Terminates process using PID verification
Script: Executes stop() function in management script

restart

Restart a shuriken (stop then start).

shurikenctl restart <NAME>

# Example
shurikenctl restart database

configure

Generate configuration from template and options.

shurikenctl configure <NAME>

# Example
shurikenctl configure webserver

Process:

Loads .ninja/options.toml
Injects {{ platform }} and {{ root }}
Renders .ninja/config.tmpl
Writes to configured path

forge

Build a .shuriken package from a directory.

shurikenctl forge [PATH]

# Interactive mode
shurikenctl forge

# Specify source directory
shurikenctl forge ./my-service

Creates: ~/.ninja/blacksmith/{id}-{platform}.shuriken

Interactive prompts:

Name and ID
Version
Platform
Synopsis and description
Authors and license

new

Create a new shuriken manifest interactively.

shurikenctl new

# Creates .ninja/manifest.toml with guided prompts

run

Execute a Ninja script.

shurikenctl run <FILE>

# Examples
shurikenctl run setup.ns
shurikenctl run scripts/deploy.lua

Executes Lua script with full Ninja API access.

api

Start the HTTP API server.

shurikenctl api [OPTIONS]

Options:
  --port <PORT>    Server port (default: 8080)

# Examples
shurikenctl api --port 3000
shurikenctl api

See API Reference for endpoints.

lockpick

Remove a stale lock file.

shurikenctl lockpick <NAME>

# Example
shurikenctl lockpick webserver

⚠️ Warning: Only use if you've verified the process is not running. Misuse can cause race conditions.

Safe usage:

# 1. Verify process is stopped
ps aux | grep service-name

# 2. Stop if needed
shurikenctl stop service-name

# 3. Remove stale lock
shurikenctl lockpick service-name

Examples

Complete Workflow

# Install package
shurikenctl install ./myapp.shuriken

# Configure
shurikenctl configure myapp

# Start
shurikenctl start myapp

# Check status
shurikenctl list

# View specific state
shurikenctl list --state

# Stop
shurikenctl stop myapp

Package Development

# Create new shuriken
shurikenctl new

# Test locally
shurikenctl start myapp

# Build package
shurikenctl forge ./myapp

# Package created at:
# ~/.ninja/blacksmith/com.example.myapp-linux-x86_64.shuriken

API Server

# Start server
shurikenctl api --port 8080

# In another terminal, use curl
curl http://localhost:8080/shurikens
curl -X POST http://localhost:8080/shurikens/myapp/start

Environment Variables

# Ninja directory (default: ~/.ninja)
export NINJA_DIR=/custom/path

# Log level
export NINJA_LOG_LEVEL=debug

Exit Codes

0 - Success
1 - General error
2 - Invalid arguments
3 - Service not found
4 - Service already running
5 - Service not running

Interactive Mode

Run shurikenctl without arguments for REPL mode:

shurikenctl

ninja> list
example-service    (Running)

ninja> configure webserver
Configuration generated successfully

ninja> exit

Help

Get help for any command:

shurikenctl --help
shurikenctl install --help
shurikenctl forge --help

CLI Reference

On this page