Skip to content

CLI reference

The ikanos CLI is the single entry point for creating, validating, importing, exporting, running and inspecting Ikanos capabilities. It ships as a runnable JAR / native image; see Installation for how to get it on your PATH.

This page is a complete reference: every command, every option, every exit code that the binary exposes. For walkthroughs, see the Guides.

Synopsis

ikanos [-hV] <command> [<subcommand>] [options] [arguments]

Global options

Option Description
-h, --help Show help and exit. Available on every command and subcommand.
-V, --version Print the schema version of the running CLI and exit.

Command catalog

Command Purpose
create Scaffold a new Ikanos resource (currently: capability).
validate Validate a capability YAML against the Ikanos JSON Schema.
import Import an external specification into Ikanos format (currently: OpenAPI).
export Export an Ikanos capability to an external format (currently: OpenAPI).
serve Run a capability YAML and block until the process is stopped.
health Check liveness & readiness of a running capability via the control port.
status Retrieve runtime status of a running capability via the control port.
metrics Fetch Prometheus metrics from the control port.
traces Inspect recent traces from the engine's ring buffer.
scripting Read or update scripting governance on a running capability.

ikanos create

Create a new Ikanos resource. Subcommands describe the resource kind.

ikanos create <subcommand>

ikanos create capability

Aliases: cap

Interactively scaffold a new capability configuration file. The command prompts on stdin for the capability name, target URI, and port, then writes a YAML capability file in the current directory.

ikanos create capability
Argument / option Description
(interactive prompts) Capability name (required), target URI (required), port (optional).

Exit codes: 0 on success, 1 if a required prompt is empty or file generation fails.

ikanos validate

Aliases: v, val

Validate a YAML capability configuration file against the Ikanos JSON Schema.

ikanos validate <file> [<schema-version>]
Positional Description
<file> Required. Path to the YAML capability configuration file to validate.
<schema-version> Optional. Schema version to validate against, format x.x (e.g. 0.5). Defaults to the latest version bundled with the CLI.

Examples

ikanos validate capability.yaml
ikanos validate capability.yaml 0.5

Exit codes: 0 if the file is valid, 1 if the file is missing, malformed, or fails schema validation.

ikanos import

Import external specifications into Ikanos format.

ikanos import <subcommand> [options]

ikanos import openapi

Import an OpenAPI (Swagger 2.0, OAS 3.0, OAS 3.1) specification into an Ikanos consumes YAML file.

ikanos import openapi <source> [options]
Argument / option Description
<source> Required. Path or URL to the OpenAPI specification file.
-o, --output <path> Output file path. Defaults to ./<namespace>-consumes.yml.
-n, --namespace <name> Override the namespace derived from the OpenAPI document.
-f, --format <yaml\|json> Output format. Defaults to yaml.

Examples

ikanos import openapi petstore.yaml
ikanos import openapi https://example.com/api.yaml -n petstore -o my-petstore.yml
ikanos import openapi petstore.yaml -f json

Exit codes: 0 on success, non-zero if the source cannot be parsed or the output cannot be written.

ikanos export

Export Ikanos capabilities to external formats.

ikanos export <subcommand> [options]

ikanos export openapi

Export a capability's REST adapter as an OpenAPI specification.

ikanos export openapi <capability> [options]
Argument / option Description
<capability> Required. Path to the Ikanos capability YAML file.
-o, --output <path> Output file path. Defaults to ./openapi.yaml.
-f, --format <yaml\|json> Output format. Defaults to yaml.
-a, --adapter <namespace> Namespace of the REST adapter to export. Required when the capability exposes more than one REST adapter.
--spec-version <3.0\|3.1> OpenAPI specification version. Defaults to 3.0.

Examples

ikanos export openapi capability.yaml
ikanos export openapi capability.yaml --spec-version 3.1 -o api-3.1.yaml
ikanos export openapi capability.yaml -a public-api -f json

Exit codes: 0 on success, non-zero if the capability cannot be loaded or the adapter cannot be resolved.

ikanos serve

Aliases: s

Run a capability and block until the process is stopped (Ctrl-C / SIGTERM). This is the same runtime that ships in the Docker image — the CLI invocation and the container invocation share an identical command contract.

ikanos serve [<file>]
Argument Description
<file> Path to the YAML capability configuration file to run. Defaults to ikanos.yaml in the working directory.

Examples

ikanos serve                       # uses ./ikanos.yaml
ikanos serve path/to/capability.yaml

💡 The Docker image defaults to ikanos serve and reads /app/ikanos.yaml if no argument is given: docker run -v "$PWD/capability.yaml:/app/ikanos.yaml" ghcr.io/naftiko/ikanos.

Exit codes: non-zero if the capability fails to start; otherwise the process runs until terminated.

Control-port commands

The following commands talk to the /health, /status, /metrics, /traces and /scripting endpoints exposed by a running capability's control port. They all share the same connection options via the ControlPortMixin:

Shared options

Option Description
--address <host> Control port host. Falls back to IKANOS_CONTROL_ADDRESS, then the address declared in the local capability YAML, then localhost.
--port <int> Control port. Falls back to IKANOS_CONTROL_PORT, then the port declared in the local capability YAML, then 9090.

ikanos health

Check the live and ready status of a running capability.

ikanos health [--address <host>] [--port <int>]

Calls GET /health/live and GET /health/ready and prints both statuses.

ikanos status

Retrieve runtime status (capability identity, uptime, started adapters, …).

ikanos status [--address <host>] [--port <int>]

Calls GET /status.

ikanos metrics

Fetch Prometheus exposition-format metrics from the control port.

ikanos metrics [--filter <regex>] [--address <host>] [--port <int>]
Option Description
--filter <regex> Regex applied to metric names; only matching metrics are printed.

ikanos traces

Inspect recent traces from the engine's ring buffer. Without an argument the command lists recent traces; with a trace ID it shows the detail of a single trace.

ikanos traces [<trace-id>] [--operation <name>] [--status <OK|ERROR>] [--address <host>] [--port <int>]
Argument / option Description
<trace-id> Optional. When provided, switches to detail mode for the given trace.
--operation <name> List mode: filter traces by operation name.
--status <OK\|ERROR> List mode: filter traces by status.

ikanos scripting

Read or update scripting governance configuration on a running capability.

ikanos scripting [--set <key=value> ...] [--address <host>] [--port <int>]
Option Description
--set <key=value> Update a scripting config field at runtime (e.g. --set enabled=true). Can be repeated. Without --set, prints the current configuration and execution stats.

Common exit codes (control-port commands): 0 if the call succeeded and the resource is healthy, 1 if the call returned a non-200 HTTP status, non-zero with a clear error message if the control port is unreachable.

Environment variables

Variable Used by Purpose
IKANOS_CONTROL_ADDRESS health, status, metrics, traces, scripting Default control-port host when --address is not provided.
IKANOS_CONTROL_PORT health, status, metrics, traces, scripting Default control-port port when --port is not provided.

Exit-code conventions

Code Meaning
0 Success.
1 The operation completed but produced a negative result (validation failed, control-port endpoint returned non-200, prompt was empty, …).
2 Unexpected exception thrown during execution.
non-zero Any other failure (I/O error, parse error, capability start-up failure, …).

See also