DSL Syntax

Complete reference for Ninja's Domain-Specific Language (DSL).

Overview

The Ninja DSL is a shell-like command language for service management and automation.

Command Structure

<command> [arguments] [options]

Core Commands

Shuriken Management

list

List installed shurikens.

# Basic list
list

# With state information
list state

Output:

example-service    (Running)
webserver          (Idle)

select

Select a shuriken for subsequent operations.

select <name>

# Example
select webserver

exit

Deselect the current shuriken.

exit

start

Start the selected shuriken.

select myapp
start

stop

Stop the selected shuriken.

select myapp
stop

install

Install a shuriken package.

install <path>

# Example
install ./service.shuriken
install ~/Downloads/com.example.app.shuriken

Configuration

configure

Generate configuration from template.

# Basic configuration
configure

# With inline options
configure {
  port = 8080
  host = "localhost"
  debug = true
}

# Multi-line block
configure {
  option1 = value1;
  option2 = value2;
  option3 = value3
}

set

Set a configuration option.

set <key> <value>

# Examples
set port 8080
set host "localhost"
set debug true

get

Get a configuration option value.

get <key>

# Example
get port

toggle

Toggle a boolean option.

toggle <key>

# Example
toggle debug

Script Execution

execute

Execute a Ninja script file.

execute <path>

# Examples
execute ./setup.ns
execute scripts/deploy.lua

HTTP Server

http

Start the HTTP API server.

http <port>

# Example
http 8080

Help

help

Display help information.

help

Value Types

The DSL automatically detects value types:

Strings

# With quotes (preserves spaces)
set message "Hello World"
set path 'C:\Program Files\App'

# Without quotes (single word)
set name value

Numbers

# Integers
set port 8080
set timeout 30

# Floats
set ratio 0.75
set delay 2.5

Booleans

set enabled true
set debug false

Comments

Both comment styles are supported:

# Hash-style comment
// Slash-style comment

configure {
  port = 8080  # Inline comment
  debug = true // Also inline
}

Configuration Blocks

Use blocks for multiple options:

configure {
  # Server settings
  port = 8080
  host = "0.0.0.0"
  workers = 4
  
  # Features
  debug = true
  ssl = false
}

Semicolon separator (optional):

configure {
  port = 8080;
  host = "localhost";
  debug = true
}

Command Chaining

Execute multiple commands:

select webserver
configure { port = 9000 }
start
list state

Deep Links

GUI supports shurikenctl:// URLs:

shurikenctl://start?shuriken=myapp
shurikenctl://stop?shuriken=myapp
shurikenctl://configure?shuriken=myapp&port=8080

Interactive Mode (REPL)

Start interactive mode:

shurikenctl

Prompt:

ninja> list
example-service    (Running)

ninja> select example-service
Selected: example-service

ninja> stop
Service stopped

ninja> exit

Script Files

Create DSL script files (.dsl extension recommended):

deploy.dsl:

# Install application
install ./myapp.shuriken

# Configure
select myapp
configure {
  port = 8080
  host = "0.0.0.0"
  workers = 4
}

# Start service
start

# Verify
list state

Execute:

shurikenctl run deploy.dsl

Error Handling

DSL commands return success/error status:

# Success
select myapp
start
# → "Service started successfully"

# Error: no such shuriken
select nonexistent
# → "No such shuriken: nonexistent"

# Error: already running
select myapp
start
# → Error: Service already running

Variables (Not Supported)

The DSL does not support variables or loops. For complex logic, use Lua scripts:

setup.ns:

-- Lua script with full Ninja API
local services = {"web1", "web2", "web3"}

for _, service in ipairs(services) do
  log.info("Starting " .. service)
  -- Use Ninja API here
end

Best Practices

Use select for multiple operations - Avoid repeating shuriken names
Group configuration - Use blocks for related options
Add comments - Document complex scripts
Error check - Verify command success before proceeding
Keep it simple - Use Lua for complex logic

Examples

Quick Start

install ./myapp.shuriken
select myapp
configure
start

Configuration Update

select webserver
set port 9000
set workers 8
configure
stop
start

Multi-Service Management

select web1
start
select web2
start
select database
start
list state

Development Workflow

# Configure and test existing shuriken
select myapp
configure { port = 3000 }
start

# Make changes
stop
# (edit files)
start

# List status
list state

Integration

With CLI

# Direct command sequence
shurikenctl run -c "select myapp"
shurikenctl run -c "start"

# Script file
shurikenctl run script.dsl

With GUI

The GUI executes DSL commands internally:

Start button → select <name> then start
Configure dialog → configure { ... }
Install button → install <path>

With HTTP API

curl -X POST http://localhost:8080/api/dsl/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "select myapp\nstart"}'

DSL Syntax

On this page