Documentation
Complete manual for scaffolding, growing, and operating SolverForge applications with solverforge-cli.
solverforge-cli
solverforge-cli is the default entry point for new SolverForge projects. It
creates a neutral web, api, cli, or mcp shell, then lets you grow that
shell with scalar and list planning variables, or both in one app, using
generator commands and ordinary Rust edits.
The CLI owns project bootstrap and code generation. The generated application then uses:
solverforgefor domain modeling and solvingsolverforge-uifor the shipped frontend in web-shell projectssolverforge-mapsfor map and routing integration in web-shell projectsrmcpfor the Model Context Protocol server in MCP-shell projects
Mental Model
Think of the CLI as a project shaper, not as a separate modeling language.
| Layer | Owner | What changes there |
|---|---|---|
| Scaffold shell | solverforge new |
Web, API, CLI, or MCP shell, config files, and app metadata |
| Domain model | CLI generators plus Rust edits | facts, entities, scalar variables, list variables, solution type |
| Constraint logic | generated skeletons, then user Rust | real hard and soft scoring rules |
| Runtime search | solver.toml |
phases, acceptors, selectors, termination, candidate limits |
| App metadata | CLI synchronization | solverforge.app.toml and, for web shells, static/generated/ui-model.json |
The generated shell is intentionally neutral. You do not choose scalar,
list, or mixed at project creation time. You add scalar and list planning
variables as the domain earns them, and the app metadata follows the Rust model.
What You Get
- A neutral scaffold that starts runnable instead of forcing a tutorial-shaped problem-class choice
web,api,cli, andmcpgenerated shells selected bysolverforge new --shell- A generated Axum backend for web/API shells with retained jobs, typed SSE events, snapshots, analysis, pause, resume, cancel, and delete flows
- An MCP shell that exposes the retained lifecycle as schema-typed tools for
agent harnesses, with
solverforge connectclient configs for opencode, Claude Code, Cursor, and VS Code - Generator commands for facts, entities, variables, constraints, solution types, score types, scalar groups, conflict repairs, and demo data
- A CLI-maintained app contract in
solverforge.app.toml - A frontend that composes shipped
solverforge-uiassets rather than vendoring a template-specific asset pipeline - A local development flow built around
solverforge server,solverforge info,solverforge check,solverforge routes, andsolverforge test, plussolverforge connectfor MCP shells - The portable
solverforge-modelingandsolverforge-uiagent skills with an agent-centric installer and an installable solve smoke test
Daily Loop
Use this loop while shaping a generated app:
solverforge info
solverforge generate fact employee
solverforge generate entity shift --field starts_at:NaiveDateTime --field ends_at:NaiveDateTime
solverforge generate variable employee_idx --entity Shift --kind scalar --range employees --allows-unassigned
solverforge generate constraint no_overlap --pair --hard
solverforge check
cargo build
solverforge test
solverforge server --debug
After each generator step, read the Rust files it touched. Every generated
constraint skeleton contains a placeholder that panics: a solve fails until you
replace it with the real rule, as the
Getting Started
guide shows. solverforge check validates structure only; cargo build is
the step that compiles the app.
Installation
cargo install solverforge-cli --locked
Update an existing install:
cargo install solverforge-cli --locked --force
Use solverforge --version to see:
- the CLI version
- the scaffold runtime, UI, maps, and MCP targets
- the exact crates.io sources used by newly generated projects
The CLI and the apps it generates need Rust 1.95 or newer.
Default Workflow
solverforge new my-scheduler
cd my-scheduler
solverforge server
Open http://localhost:7860 after the server starts. The fresh shell solves its
empty plan to 0hard/0soft; the
Getting Started guide grows it into a
task assignment model and solves that.
The default web shell is intentionally thin. It starts with a neutral Plan
solution, solver lifecycle routes, solverforge-ui-backed frontend assets, and
no domain-specific assumptions beyond the SolverForge runtime contract.
When To Use It
Use solverforge-cli when you want the fastest path from zero to a running
SolverForge app and you want to shape the model incrementally instead of
starting from a fixed tutorial repository.
Use the long-form use cases after you understand the generic shell. They show complete app work, data generation, frontend decisions, and deployment shape; they are not replacements for the CLI-first project model.
Boundaries
The CLI keeps generated structure coherent, but it does not decide the planning model for you.
- It scaffolds facts, entities, variables, constraints, scalar groups, conflict repairs, demo data, and metadata.
- It keeps managed blocks and
solverforge.app.tomlsynchronized. - It does not infer business rules from field names.
- It does not write constraint rules: generated skeletons panic until you replace their placeholders.
- It does not replace runtime-level
solver.tomltuning when a model needs a different construction, selector, acceptor, or termination policy.
Sections
- Getting Started - install the CLI, scaffold a project, run the server, and make the first model changes
- Project Anatomy - generated file layout, ownership boundaries, and managed markers
- Modeling & Generation - facts, entities, scalar variables, list variables, constraints, data, and destroy flows
- Configuration -
solver.toml,solverforge.app.toml, UI metadata, and scaffold target versioning - Command Reference - command groups, version output, global options, and focused command-reference subsections
- MCP Shell - the
mcpshell, its tool surface, andsolverforge connect - Agent Skill - the portable
solverforge-modelingskill and its solve smoke test