CLI Commands & Onboarding
Relevant source files
The following files were used as context for generating this wiki page:
The Noesis CLI serves as the primary entry point for the application, managing session lifecycle, environment configuration, and model authentication. It facilitates both interactive use through a Terminal User Interface (TUI) and administrative tasks such as workspace inspection, database rebuilding, and credential management.
The onboarding system ensures a frictionless first-launch experience by detecting missing configurations and guiding the user through provider selection and authentication. This module adheres to the core engineering invariant of validating all unknown durable data at the boundary while maintaining a strictly typed ESM Node.js environment.
Sources: apps/noesis/src/cli.ts:1-25, AGENTS.md:1-55
CLI Architecture and Command Structure
The CLI is structured around a central parser that resolves arguments into a CliInput interface. It distinguishes between primary commands, subcommands (for config and auth), and agent-specific overrides.
Command Execution Flow
The main() function in the CLI coordinates the transition from raw arguments to a running application runtime. It first parses the arguments, handles help or configuration requests, and then proceeds to either trigger onboarding or initialize the TUI/inspection services.
Sources: apps/noesis/src/cli.ts:326-407
Primary CLI Commands
The CLI supports the following operational commands:
| Command | Subcommand / Option | Description |
|---|---|---|
tui | --resume, --continue | Starts the interactive Terminal User Interface. |
onboard | N/A | Forces the interactive first-launch setup flow. |
inspect | N/A | Exports the current state of trails and active capability revisions in JSON format. |
rebuild | N/A | Triggers a rebuild of the SQLite search documents for the workspace. |
config | init, show, set | Manages the config.json file and displays resolved settings. |
auth | status, login, logout | Manages authentication states for providers like OpenAI or OpenRouter. |
help | N/A | Displays usage information and session startup rules. |
Sources: apps/noesis/src/cli.ts:161-190, apps/noesis/test/cli.test.ts:50-100
Session Startup Modes
The CLI provides specific flags to control how a session begins:
- New Session: The default behavior when no startup flags are provided.
--continue: Resumes the single most recently active session. It is rejected if the session is still marked as running.--resume [ID]: Resumes a specific session by ID. If no ID is provided, it enters an interactive picker mode.
Sources: apps/noesis/src/cli.ts:192-205, apps/noesis/test/cli.test.ts:102-125
First-Launch Onboarding
Onboarding is an automated process triggered when a config.json is missing or when a user explicitly runs the onboard command. It utilizes a set of interactive prompts to configure the workspace and authenticate with LLM providers.
Auto-Onboarding Logic
The system determines if onboarding is necessary based on several environmental factors:
- Config Existence: Whether a configuration file already exists in the
NOESIS_HOMEdirectory. - Interactivity: Onboarding requires an interactive TTY (stdin/stdout).
- Explicit Settings: If the user provides explicit agent settings (e.g., via environment variables or CLI flags), auto-onboarding may be bypassed.
Prompt Interfaces
The onboarding process defines a standard OnboardingPrompts interface to abstract the user interaction layer:
choose: Presents a list of options for selection.text: Requests a string input with a default value.confirm: Requests a boolean (Yes/No) response.note: Displays an informational message to the user.
Sources: apps/noesis/src/onboarding.ts:15-30, apps/noesis/src/cli.ts:285-320
Expert Controls and Extensions
Beyond basic startup, the CLI and TUI provide "Expert Controls" for deep system manipulation. These commands allow developers and power users to inspect the autonomous compounding features of Noesis.
Control Plane Operations
As defined in the implementation plans, the CLI is intended to support advanced background management:
noesis worker: A planned command to launch a resident background worker for autonomous reflection and evaluation tasks.noesis config set: Dynamically updates the configuration with new agent options or thinking levels.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:Task AC-12, apps/noesis/src/cli.ts:250-265
TUI Expert Shortcuts
While primarily accessed via the TUI, these logical commands are handled by the runtime command port that the CLI initializes:
/changes: Lists recent experiments and capability activations./why: Explains the active turn and specific definition revisions used./revert: Restores the previous active capability revision./criteria: Manages explicit user-owned instructions.
Sources: plans/compounding-partnership-product-loop.html:WS5, plans/noesis-autonomous-compounding-implementation-plan.html:Product Experience
Configuration and Environment
The CLI resolves configuration from multiple sources in a specific order of precedence:
- CLI Overrides: Flags like
--provideror--model. - Environment Variables:
NOESIS_HOME,NOESIS_PROVIDER,NOESIS_MODEL, etc. config.json: The persistent configuration file in the home directory.
Agent Options
These options can be applied to tui, inspect, rebuild, and config commands:
--provider: The ID of the LLM provider (e.g.,openai-codex).--model: The specific model ID to utilize.--thinking-level: The reasoning level for models that support it.--home: Custom path for the Noesis workspace (defaults to.noesis).
Sources: apps/noesis/src/cli.ts:108-140, apps/noesis/test/cli.test.ts:127-145
The CLI implementation ensures that any fault before admission (e.g., malformed arguments) produces no visible turn or state change, while settled turns result in a single authoritative SQLite entry.
Sources: plans/compounding-partnership-product-loop.html:WS1, AGENTS.md:1-55