Metadata-Version: 2.4
Name: msapling-cli
Version: 0.1.11
Summary: MSapling CLI - Multi-chat AI development environment in your terminal
Author: MSapling Team
License-Expression: MIT
Project-URL: Homepage, https://msapling.com
Project-URL: Documentation, https://docs.msapling.com
Project-URL: Repository, https://github.com/Kandy00/CLI
Project-URL: Issues, https://github.com/Kandy00/CLI/issues
Keywords: ai,cli,chat,code,llm,multi-model
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Code Generators
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: cryptography>=41.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: pyreadline3>=3.4; sys_platform == "win32"
Provides-Extra: keyring
Requires-Dist: keyring>=24.0; extra == "keyring"
Provides-Extra: tui
Requires-Dist: textual>=0.40.0; extra == "tui"
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10.0; extra == "pdf"
Provides-Extra: all
Requires-Dist: keyring>=24.0; extra == "all"
Requires-Dist: textual>=0.40.0; extra == "all"
Requires-Dist: pdfplumber>=0.10.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-html>=4.1.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# MSapling CLI

MSapling CLI is a multi-chat, multi-model AI development environment in your terminal that stays connected to the same backend state as the MSapling web app.

Unlike local-only coding CLIs, MSapling is designed around shared backend projects, shared chats, shared budgets, and shared account state. If you create a project or chat in the web app, the CLI should see it. If you spend budget or create workers in the CLI, that state should be visible across the platform.

## Status

`msapling-cli` is in beta hardening.

What that means today:
- It is already usable for real work.
- It has a broader command surface than a toy CLI.
- It is still being hardened for production-readiness, especially around release discipline, live backend contract coverage, and enterprise/operator controls.

Current local validation baseline during this hardening line:
- Windows / Python 3.13 focused and full CLI suites have recently been green in the active worktree.
- Live smoke coverage is in `scripts/release_smoke.py`.
- Supporting docs live in [`docs/`](docs/README.md).

## Table Of Contents

- [What MSapling CLI Is](#what-msapling-cli-is)
- [Core Product Principles](#core-product-principles)
- [Install](#install)
- [Authentication](#authentication)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [Command Guide](#command-guide)
- [Interactive Shell](#interactive-shell)
- [Projects, Chats, Workers, And Budgets](#projects-chats-workers-and-budgets)
- [Models](#models)
- [Code Editing And Diff Workflows](#code-editing-and-diff-workflows)
- [MCP Support](#mcp-support)
- [Diagnostics And Health Checks](#diagnostics-and-health-checks)
- [Configuration](#configuration)
- [Architecture Notes](#architecture-notes)
- [Security And Safety Model](#security-and-safety-model)
- [Known Limitations](#known-limitations)
- [Operator And Release Notes](#operator-and-release-notes)
- [Documentation Index](#documentation-index)

## What MSapling CLI Is

MSapling CLI combines several ideas in one product:
- A normal single-chat CLI for quick prompts.
- An interactive shell for longer sessions.
- A multi-worker environment where several chats can run side by side.
- A shared project/chat system backed by the MSapling backend instead of isolated local transcripts only.
- A multi-model interface that can route across many model providers.
- A coding-oriented CLI with editing, diffing, scan/context building, benchmarking, and MCP support.

The long-term product idea is not "another thin prompt wrapper." The goal is a serious CLI that can act as the command-line face of the full MSapling platform.

## Core Product Principles

### 1. Shared backend state
The CLI is not supposed to diverge from the web product.

These should line up across CLI and web:
- projects
- chats
- chat history
- budgets and usage
- model routing outcomes
- account tier and fuel credits

### 2. Multi-chat by default
MSapling is built around the idea that one developer may want several active tracks at once:
- a main coding thread
- one or more workers
- benchmark or comparison lanes
- a maintenance or ops project

### 3. Multi-model, not single-vendor
MSapling is intended to work across many providers and model families. The CLI should expose that power without making model selection fragile or misleading.

### 4. Operator visibility matters
This project is intended to scale beyond hobby use. That means:
- budgets and cost visibility matter
- diagnostics matter
- shared state matters
- release quality matters

## Install

### From PyPI

```bash
pip install msapling-cli
```

### Upgrade

```bash
pip install --upgrade msapling-cli
```

### From GitHub

```bash
pip install git+https://github.com/Kandy00/CLI.git
```

### From local source

```bash
cd cli
pip install -e .
```

## Authentication

Login uses your MSapling account:

```bash
msapling login
```

Useful auth/account commands:

```bash
msapling whoami
msapling doctor
msapling config
```

Token source precedence is intentionally deterministic:
- `MSAPLING_TOKEN`
- local token file
- keyring

That keeps automation reliable and makes `doctor` capable of reporting auth mismatches.

## Quick Start

### Basic one-shot chat

```bash
msapling chat "Explain Python async vs threads"
```

### Interactive session

```bash
msapling chat -i
```

### Choose a model

```bash
msapling chat -m anthropic/claude-3-haiku "Summarize this repo"
```

### Scan a project locally

```bash
msapling scan .
msapling context .
```

### Compare models

```bash
msapling multi "Design a retry policy for this API"
msapling benchmark "Write a fast JSON parser"
```

### Edit files with AI help

```bash
msapling edit "Refactor this function for readability" path/to/file.py
```

## Core Concepts

### Project
A project is the top-level shared container. Projects are backend objects, not just local folders.

### Chat
A chat is a backend conversation associated with a project. CLI and web should both see the same chat state.

### Worker
A worker is an additional chat lane created for parallel or role-specific work. Workers have their own model, status, token usage, and cost accounting.

### Default Project
If you do not explicitly target a project, the CLI can fall back to `Default Project`.

That is useful, but it also means careless one-shot chat creation can clutter the shared backend. Recent hardening work has focused on reducing unnecessary quick-chat sprawl there.

### Fuel / budget
MSapling tracks account-level fuel credits and CLI session usage. Budgets are meant to be visible and enforceable, especially when running multiple workers.

## Command Guide

The exact command surface evolves, but the CLI broadly covers these areas.

### Chat and interaction
- `msapling chat "..."`
- `msapling chat -i`
- `msapling multi "..."`
- `msapling swarm "..."`
- `msapling benchmark "..."`
- `msapling resume`
- `msapling sessions`
- `msapling streams`
- `msapling logs`

### Project and account inspection
- `msapling projects`
- `msapling whoami`
- `msapling models`
- `msapling config`
- `msapling config theme`
- `msapling config theme --list`
- `msapling doctor`
- `msapling doctor --json`
- `msapling doctor --json --strict`
- `msapling dev status`
- `msapling export status`
- `msapling providers status`

### Local repository understanding
- `msapling scan .`
- `msapling context .`
- `msapling diff old.py new.py`

### Code modification
- `msapling edit "instruction" file.py`

### Git helpers
- `msapling git status`
- `msapling git log`
- `msapling path-check`
- `msapling upgrade`

### Orchestration And Release
- `msapling pipeline create`
- `msapling pipeline list`
- `msapling pipeline run`

### Integrations
- `msapling mcp-serve`
- plugin discovery and extension packaging are described in `docs/plugin_spec.md`

Use `msapling --help` for the current top-level command list.

## Interactive Shell

Inside the interactive shell, the product becomes more than a one-shot command wrapper.

The shell supports:
- resumed backend chats
- recovery from stale session and lock state
- project selection
- worker creation and joining
- model switching
- budgets and cost inspection
- slash commands
- image attachment flows
- agent mode and simple mode
- a theme-aware prompt and status bar that follow `msapling config theme`

Examples of useful shell commands include:
- `/help`
- `/models`
- `/model ...`
- `/status`
- `/budget 0.05`
- `/cost`
- `/workers`
- `/join 1`
- `/worker 1`
- `/files path`
- `/read path`
- `/vim`

### Multiline paste behavior
Recent hardening work improved Windows paste handling so pasted blocks are batched instead of being sent line by line. Terminal transcript pastes are also sanitized into quoted context instead of being treated like fresh shell commands.

### Working indicators
The shell includes a live working/streaming indicator so agent tasks do not appear idle while the model is still processing.

## Projects, Chats, Workers, And Budgets

### Shared project model
The CLI should reflect the same project counts, chat counts, and limits that exist in the backend and web UI.

### Worker model
Workers are stored as separate chat lanes. They are useful for:
- trying different models on the same task
- parallel exploration
- keeping one main thread clean while delegating side work

### Budgets
Budgets are important because MSapling is designed for multi-chat and multi-model use. Cost visibility is not optional in that setup.

Current design intent:
- show session usage clearly
- show worker usage clearly
- stop or warn when budget is hit
- keep account-level fuel visible

## Models

MSapling can expose many models from multiple providers. The long-term product requirement is not just a large catalog, but a trustworthy catalog.

A good MSapling model UX should guarantee:
- valid model IDs
- clear alias resolution
- no silent acceptance of invalid user input
- no listing of models that the current user cannot actually route to

If model behavior looks wrong, start with:

```bash
msapling models
msapling doctor --json
```

## Code Editing And Diff Workflows

MSapling CLI is intended to be coding-native, not just chat-native.

Key capabilities:
- scan a repo
- build context for a repo
- diff files
- edit files with AI guidance
- run agent workflows for code tasks
- benchmark or compare model output on coding prompts

The broader product direction favors diff-aware workflows and practical coding operations over giant raw-file rewrites.

## MCP Support

MSapling can run as an MCP server.

The MCP surface is intentionally split between server hosting and client-side discovery:
- `msapling mcp-serve` exposes the backend as an MCP server
- `docs/plugin_spec.md` describes the current extension packaging and hook discovery contract
- `msapling doctor --json` reports the health checks that operators should review before relying on the integration

Preferred launch forms:

```bash
# Source/dev-safe invocation
py -3.13 -m msapling_cli.main mcp-serve

# Installed CLI, if `msapling` is already on PATH
msapling mcp-serve
```

Example Claude Code configuration:

```json
{
  "mcpServers": {
    "msapling": {
      "command": "py",
      "args": ["-3.13", "-m", "msapling_cli.main", "mcp-serve"],
      "env": {
        "MSAPLING_TOKEN": "your-token"
      }
    }
  }
}
```

If you prefer `"command": "msapling"`, make sure the installed package is current and the Python Scripts directory is actually on PATH for the process launching Claude Code or Cursor.

This makes MSapling useful not only as a user-facing CLI, but also as an integration surface for other AI tooling.

## Diagnostics And Health Checks

### Doctor

```bash
msapling doctor
msapling doctor --json
msapling doctor --json --strict
msapling doctor --exhaustive
```

`doctor` is the first place to look when something feels off.

It is intended to surface:
- install health
- auth source in use
- auth conflicts or drift
- API connectivity
- authenticated account checks
- missing optional tooling
- local runtime matrix state

For live account and operator snapshots, use:
- `msapling dev status`
- `msapling providers status`
- `msapling export status`

Related recovery commands:
- `msapling sessions`
- `msapling resume`
- `msapling streams`
- `msapling logs`
- `msapling path-check`
- `msapling upgrade`

### Release smoke

```bash
python scripts/release_smoke.py
```

Use this before releasing or after changing runtime-sensitive CLI behavior.

## Configuration

`msapling config` shows current config values and runtime-relevant settings.

Examples of behavior/configuration ideas that matter in practice:
- auth token source
- model defaults
- API endpoint selection
- theme selection for the shell prompt and status bar
- legacy instruction loading
- optional integrations

Use `msapling config theme` to inspect the active theme and `msapling config theme --list` to see the built-in palette options.

### Optional MLineage Tracing

You can stream CLI conversation and shell events into MLineage when you want
local traceability for audits/version lineage.

```bash
# Enable bridge (disabled by default)
setx MSAPLING_MLINEAGE_ENABLE 1

# Optional project_id override in lineage events
setx MSAPLING_MLINEAGE_PROJECT_ID MSapling
```

When enabled, MSapling CLI records:
- user and assistant chat turns
- `/run` command executions
- `/git` command executions

If `mlineage` is not installed, CLI behavior is unchanged (the bridge soft-fails).

### Legacy instruction files
MSapling prefers project-native instruction files, but it can optionally load legacy files such as `CLAUDE.md` and `GEMINI.md` when explicitly enabled.

That behavior should stay opt-in so old archived instruction files do not silently contaminate current chat context.

## Architecture Notes

At a high level, the CLI has several responsibilities:
- terminal UX
- backend API integration
- local repo understanding
- model selection and routing interface
- chat/project synchronization
- cost and budget tracking
- integration surface for MCP and related tooling

The CLI is not the entire product. It is a client of the broader MSapling platform.

That means production quality depends on both:
- solid local CLI behavior
- accurate backend contracts

## Security And Safety Model

The CLI is powerful, so its safety model matters.

Key areas that need to stay strong:
- deterministic auth handling
- clear local file access boundaries
- command execution controls
- safe transcript handling
- no misleading claims about unavailable tools or inaccessible local state
- honest budgets and cost reporting

This area is still actively hardening.

## Known Limitations

Current known limitations or areas still under active work include:
- some model catalog entries may still be listed before full routability filtering is enforced
- long-lived shared chats can carry stale context if they were previously poisoned by bad assistant behavior
- backend contract changes still require strong live smoke coverage to avoid CLI drift
- enterprise-grade managed settings, policy controls, and admin surfaces are not fully built out yet

## Operator And Release Notes

MSapling CLI is being hardened toward production-readiness, not just new features.

That means the release bar should include:
- green tests
- build success
- live smoke success
- docs updated
- version metadata aligned
- PyPI/GitHub release consistency
- docs updated for recovery, diagnostics, orchestration, MCP discovery, and platform notes

Useful local commands:

```bash
py -3.13 -m pytest tests -q
py -3.13 -m build
py -3.13 scripts/release_smoke.py
```

Windows-safe runner (handles temp ACL quirks):

```powershell
scripts\run_tests.bat
```

For platform-specific setup and runtime notes, see:
- `docs/dev_setup_windows.md`
- `docs/local_runtime_matrix.md`
- `docs/production-readiness.md`

## Documentation Index

Additional docs live here:
- [Docs index](docs/README.md)
- [Production readiness](docs/production-readiness.md)
- [Release checklist](docs/release-checklist.md)
- [Competitive readiness](docs/competitive-readiness.md)

## Links

- Website: https://msapling.com
- Pricing: https://msapling.com/pricing
- Repository: https://github.com/Kandy00/CLI

## Bottom Line

MSapling CLI is trying to be more than a local prompt shell.

The differentiator is the combination of:
- shared backend state
- multi-chat / multi-worker workflows
- multi-model access
- coding-focused operations
- platform integration with the rest of MSapling

The current mission is to make that ambitious shape reliable enough that users can trust it in real development work.
