Builtin Services: Shell

The built-in shell lets you interact with your running services through the terminal or TUI. You can register your own commands to expose functionality at runtime. Useful for admin tasks, debugging, or controlling your services without restarting.

Registering a Command

Use RegisterCommand to define a new shell command. Import it from nautica.services.builtins.shell.decorator:

from nautica.services.builtins.shell.decorator import RegisterCommand, CommandRequirements

@RegisterCommand(
    "greet",
    "Prints a greeting message"
)
def greet():
    return "Hello from MyService!"

Commands should be registered in onStart()

from nautica import Service
from nautica.services.builtins.shell.decorator import RegisterCommand

class MyService(Service):
    def onStart(self):
        from . import commands  # import your commands module here

Service.Export(MyService)

Returning a string from a command prints it as an OK log. If you don't return anything, nothing is printed.

Arguments

Use CommandRequirements to define expected arguments for a command:

from nautica.services.builtins.shell.decorator import RegisterCommand, CommandRequirements

@RegisterCommand(
    "greet",
    "Greets a user by name",
    args = CommandRequirements(
        args = {"name": str}
    )
)
def greet(name: str):
    return f"Hello, {name}!"

Arguments are passed positionally in the shell:

> greet Martin
Hello, Martin!

Supported Types

Type	Behavior
str	Passed as-is
int	Coerced from string
float	Coerced from string
bool	Accepts true/false, 1/0, yes/no

Validators

You can use Requirement validators instead of plain types:

from nautica.models.Requirements import AnyOf

@RegisterCommand(
    "setmode",
    "Sets the service mode",
    args = CommandRequirements(
        args = {"mode": AnyOf("debug", "production")}
    )
)
def setmode(mode: str):
    return f"Mode set to {mode}"

> setmode debug
Mode set to debug

> setmode invalid
Command failed to execute: Argument <mode> does not match anyOf(debug, production)

Learn more at: https://github.com/xellu/nautica-api/wiki/Requirement-Validators

Flags

Flags are optional boolean switches prefixed with --:

@RegisterCommand(
    "stop",
    "Stops all services",
    args = CommandRequirements(
        flags = ["force"]
    )
)
def stop(force: bool = False):
    if force:
        import os
        os._exit(1)
    
    from nautica import Services
    Services.onClose("requested by user")

> stop           # graceful shutdown
> stop --force   # immediate exit

Combining Arguments and Flags

@RegisterCommand(
    "reload",
    "Reloads a service",
    args = CommandRequirements(
        args = {"service": str},
        flags = ["verbose"]
    )
)
def reload(service: str, verbose: bool = False):
    if verbose:
        Logger.info(f"Reloading {service}...")
    return f"Reloaded {service}"

> reload HTTPServer
> reload HTTPServer --verbose

Accessing Services

Commands have access to the full runtime, so you can interact with any running service:

from nautica import Services, Logger

@RegisterCommand("status", "Shows service status")
def status():
    for s in Services.instances:
        Logger.info(f"{s._getName()}: running")

Full Example

A service that registers several admin commands:

from nautica import Service, Logger, Config, Services
from nautica.services.builtins.shell.decorator import RegisterCommand, CommandRequirements
from nautica.models.Requirements import AnyOf

class AdminService(Service):
    def onStart(self):
        @RegisterCommand(
            "admin.status",
            "Shows all running services"
        )
        def status():
            for s in Services.instances:
                Logger.info(f" * {s._getName()}")

        @RegisterCommand(
            "admin.setdebug",
            "Toggles debug mode",
            args = CommandRequirements(
                args = {"value": bool}
            )
        )
        def setdebug(value: bool):
            Config("nautica")["nautica.debug"] = value
            return f"Debug mode set to {value}"

        @RegisterCommand(
            "admin.loglevel",
            "Sets the log level",
            args = CommandRequirements(
                args = {"level": AnyOf("info", "warn", "error", "debug")}
            )
        )
        def setloglevel(level: str):
            return f"Log level set to {level}"

Service.Export(AdminService)

> admin.status
> admin.setdebug true
> admin.loglevel warn