msapling-cli 0.1.11

MSapling CLI - Multi-chat AI development environment in your terminal

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/.

Table Of Contents

• What MSapling CLI Is
• Core Product Principles
• Install
• Authentication
• Quick Start
• Core Concepts
• Command Guide
• Interactive Shell
• Projects, Chats, Workers, And Budgets
• Models
• Code Editing And Diff Workflows
• MCP Support
• Diagnostics And Health Checks
• Configuration
• Architecture Notes
• Security And Safety Model
• Known Limitations
• Operator And Release Notes
• 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

pip install msapling-cli

Upgrade

pip install --upgrade msapling-cli

From GitHub

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

From local source

cd cli
pip install -e .

Authentication

Login uses your MSapling account:

msapling login

Useful auth/account commands:

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

msapling chat "Explain Python async vs threads"

Interactive session

msapling chat -i

Choose a model

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

Scan a project locally

msapling scan .
msapling context .

Compare models

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

Edit files with AI help

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:

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:

# 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:

{
  "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

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

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.

# 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:

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):

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
• Production readiness
• Release checklist
• Competitive readiness

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.