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:

  • solverforge for domain modeling and solving
  • solverforge-ui for the shipped frontend in web-shell projects
  • solverforge-maps for map and routing integration in web-shell projects
  • rmcp for 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, and mcp generated shells selected by solverforge 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 connect client 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-ui assets rather than vendoring a template-specific asset pipeline
  • A local development flow built around solverforge server, solverforge info, solverforge check, solverforge routes, and solverforge test, plus solverforge connect for MCP shells
  • The portable solverforge-modeling and solverforge-ui agent 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.toml synchronized.
  • 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.toml tuning 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 mcp shell, its tool surface, and solverforge connect
  • Agent Skill - the portable solverforge-modeling skill and its solve smoke test

External References