src

The `lms` CLI tool for LM Studio — a Commander.js-based command-line interface that lets users manage local LLM models, interact with a running LM Studio daemon, run interactive chat sessions in the terminal, manage runtime engines, develop plugins, and handle authentication and project operations against the LM Studio platform.

Tech Stack

ReactZod

Key Features

Model Discovery & Download
Interactive Terminal Chat
Model Lifecycle Management
Model Import
Daemon Lifecycle Control
Runtime Engine Management
Plugin Development Runner
Authentication & Project Operations
Experiment Flags
Authenticated Client Factory
Persistent CLI Preferences

Entry Points

Start here when working with this codebase

index.ts

src/index.ts

Application entry point

Start here to understand how the application initializes

Coding Conventions

Standards and patterns used in this codebase

Architecture

Use a subcommand-based CLI architecture with Commander.js, where each subcommand is defined in its own module under src/subcommands/ and registered in the main entry point

Each command like 'chat', 'daemon', 'dev' has its own directory or file under src/subcommands/, and src/index.ts orchestrates registration

src/index.tssrc/subcommands/create.tssrc/subcommands/chat

Data Persistence

Use a generic file-based data persistence layer with reactive signals and file watching (FileData pattern) for local state, combined with Zod schema validation for configuration

FileData.ts provides reactive file-backed storage; cliPref.ts uses Zod schemas to validate persisted CLI preferences

src/FileData.tssrc/cliPref.ts

TypeScript Patterns

Organize shared types and helper utilities into a dedicated types directory (src/types/) with focused modules for specific concerns like version comparison, architecture labels, and project discovery

Separate modules for version comparison, architecture labels, and project discovery under src/types/

src/types

UI/UX

Use Ink (React-based terminal UI framework) for interactive terminal experiences, with dedicated React component directories for complex interactive features

The chat feature uses src/subcommands/chat/react/ for Ink-based React terminal UI components for the interactive chat experience

src/subcommands/chat/reactsrc/ProgressBar.ts

Client Infrastructure

Centralize client creation through a factory module that handles authentication, connection management, and server discovery, rather than instantiating clients directly in commands

createClient.ts serves as the single factory for LMStudioClient instances with auth and connection config

src/createClient.tssrc/ensureAuthenticated.ts

Error Handling & Auth

Enforce authentication as a reusable guard/middleware pattern that can be applied to any CLI operation requiring user credentials

ensureAuthenticated.ts provides a reusable authentication enforcement function used before protected operations

src/ensureAuthenticated.ts

File Organization

Keep shared infrastructure utilities (logging, paths, prompts, formatting) as flat modules in the src/ root, while feature-specific logic lives in nested subcommand directories

lmstudioPaths.ts, logLevel.ts, and formatting utilities live at src/ root; feature commands are nested under src/subcommands/

src/lmstudioPaths.tssrc/logLevel.tssrc/subcommands/daemon

Progress & Feedback

Implement download and long-running operation feedback through dedicated progress bar and spinner abstractions that handle user interruption (e.g., Ctrl+C signals)

handleDownloadWithProgressBar.ts manages downloads with progress display and graceful interruption handling; ProgressBar.ts provides animated terminal progress

src/handleDownloadWithProgressBar.tssrc/ProgressBar.ts

Configuration

Define all file system paths for configuration and data directories in a single centralized paths module rather than scattering path construction across the codebase

lmstudioPaths.ts exports all paths for LM Studio config and data directories used throughout the CLI

src/lmstudioPaths.ts