cli

README

CLI Input Component

Interactive command-line interface for the SemStreams agentic system.

Overview

The CLI input component provides terminal-based interaction with the router and agentic loops. It reads user input from stdin, publishes messages to NATS, displays responses, and handles Ctrl+C signals for loop cancellation.

Configuration

{
  "user_id": "coby",
  "session_id": "terminal-1",
  "prompt": "> ",
  "stream_name": "USER"
}

Field	Type	Default	Description
user_id	string	cli-user	User identifier for permissions
session_id	string	cli-session	Unique session identifier
prompt	string	>	Input prompt displayed to user
stream_name	string	USER	JetStream stream name

NATS Subjects

Subject	Direction	Description
user.message.cli.{session_id}	Publish	User input messages
user.response.cli.{session_id}	Subscribe	Responses from router
user.signal.{loop_id}	Publish	Cancel signals (Ctrl+C)

Local Commands

These commands are handled by the CLI component itself:

Command	Description
/quit, /exit	Exit the CLI session
/clear	Clear active loop tracking

All other input (including /commands) is forwarded to the router.

Signal Handling

Signal	Behavior
Ctrl+C	Send cancel signal for active loop
Ctrl+D	Exit (EOF)

If no loop is active when Ctrl+C is pressed, a message is displayed. Press Ctrl+C again to exit.

Response Types

The CLI formats responses based on their type:

Type	Display Format
error	[ERROR] message
status	[STATUS] message
result	[RESULT]\nmessage
prompt	[PROMPT] message with action buttons
stream	Raw content (for streaming output)
text	Plain message

Example Session

> Hello, can you help me review main.go?

[STATUS] Task submitted. Loop: loop_abc123

[RESULT]
I've reviewed main.go and found the following...

> /cancel

Cancel signal sent for loop loop_abc123

> /quit
Goodbye!

Metrics

The component exports Prometheus metrics:

Metric	Type	Description
cli_messages_published_total	counter	Messages sent to router
cli_responses_received_total	counter	Responses received by type
cli_signals_sent_total	counter	Cancel signals sent

Integration

The CLI component works with the router component:

1. User types input
2. CLI publishes to user.message.cli.*
3. Router processes and publishes task or command response
4. CLI receives response on user.response.cli.*
5. CLI displays formatted response

See the Agentic Dispatch documentation for command handling details.

Documentation

Overview

Package cli provides a CLI input component for interactive user sessions. It reads from stdin, publishes user messages to NATS, and handles Ctrl+C signals.

Package cli provides a CLI input component for interactive user sessions.

The CLI input component reads from stdin, publishes user messages to the router via NATS, displays responses, and handles Ctrl+C signals for loop cancellation.

Architecture

The CLI component is an input component that bridges terminal interaction with the agentic system:

┌─────────────┐     user.message.cli.*     ┌────────────┐
│             │ ──────────────────────────▶│            │
│  CLI Input  │                            │   Router   │
│             │◀────────────────────────── │            │
└─────────────┘     user.response.cli.*    └────────────┘
      │
      │ Ctrl+C
      ▼
user.signal.{loop_id}

NATS Subjects

The component uses three subject patterns:

• user.message.cli.{session_id} - Published when user enters text
• user.response.cli.{session_id} - Subscribed for router responses
• user.signal.{loop_id} - Published on Ctrl+C to cancel active loop

Local Commands

Some commands are handled locally without routing to the server:

• /quit, /exit - Exit the CLI session
• /clear - Clear the active loop tracking

All other input (including /commands) is published to the router.

Configuration

The component is configured via JSON:

{
  "user_id": "coby",
  "session_id": "terminal-1",
  "prompt": "> ",
  "stream_name": "USER"
}

Signal Handling

Pressing Ctrl+C sends a cancel signal for the currently active loop. If no loop is active, it displays a message. Press Ctrl+C twice to exit when no loop is running.

Example Usage

The CLI component is typically created via the component registry:

config := json.RawMessage(`{
  "user_id": "coby",
  "session_id": "session-001"
}`)
comp, err := cli.NewComponent(config, deps)
if err != nil {
  log.Fatal(err)
}
comp.Start(ctx)

Package cli provides Prometheus metrics for CLI input component.

Index

• func NewComponent(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)
• func Register(registry *component.Registry) error
• type Component
  • func (c *Component) ConfigSchema() component.ConfigSchema
  • func (c *Component) DataFlow() component.FlowMetrics
  • func (c *Component) GetActiveLoop() string
  • func (c *Component) Health() component.HealthStatus
  • func (c *Component) Initialize() error
  • func (c *Component) InputPorts() []component.Port
  • func (c *Component) Meta() component.Metadata
  • func (c *Component) OutputPorts() []component.Port
  • func (c *Component) SetActiveLoop(loopID string)
  • func (c *Component) SetReader(r io.Reader)
  • func (c *Component) SetWriter(w io.Writer)
  • func (c *Component) Start(ctx context.Context) error
  • func (c *Component) Stop(timeout time.Duration) error
• type Config
  • func DefaultConfig() Config
  • func (c Config) Validate() error

Functions

func NewComponent

func NewComponent(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)

NewComponent creates a new CLI input component

func Register

func Register(registry *component.Registry) error

Register registers the CLI input component factory with the registry

Types

type Component

type Component struct {
	// contains filtered or unexported fields
}

Component implements the CLI input processor

func (*Component) ConfigSchema

func (c *Component) ConfigSchema() component.ConfigSchema

ConfigSchema returns the configuration schema

func (*Component) DataFlow

func (c *Component) DataFlow() component.FlowMetrics

DataFlow returns current data flow metrics

func (*Component) GetActiveLoop

func (c *Component) GetActiveLoop() string

GetActiveLoop returns the active loop ID

func (*Component) Health

func (c *Component) Health() component.HealthStatus

Health returns current health status

func (*Component) Initialize

func (c *Component) Initialize() error

Initialize prepares the component

func (*Component) InputPorts

func (c *Component) InputPorts() []component.Port

InputPorts returns input port definitions

func (*Component) Meta

func (c *Component) Meta() component.Metadata

Meta returns component metadata

func (*Component) OutputPorts

func (c *Component) OutputPorts() []component.Port

OutputPorts returns output port definitions

func (*Component) SetActiveLoop

func (c *Component) SetActiveLoop(loopID string)

SetActiveLoop sets the active loop ID (for testing)

func (*Component) SetReader

func (c *Component) SetReader(r io.Reader)

SetReader sets the input reader (for testing)

func (*Component) SetWriter

func (c *Component) SetWriter(w io.Writer)

SetWriter sets the output writer (for testing)

func (*Component) Start

func (c *Component) Start(ctx context.Context) error

Start begins the CLI input loop

func (*Component) Stop

func (c *Component) Stop(timeout time.Duration) error

Stop halts the CLI input with graceful shutdown

type Config

type Config struct {
	UserID     string                `json:"user_id"`
	SessionID  string                `json:"session_id"`
	Prompt     string                `json:"prompt"`
	StreamName string                `json:"stream_name"`
	Ports      *component.PortConfig `json:"ports,omitempty"`
}

Config represents the configuration for the CLI input component

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default configuration

func (Config) Validate

func (c Config) Validate() error

Validate validates the configuration