Command-line workflows

Operate the local server and tools with the commands supported by this build.

The mellow command connects scripts and developer tools to the installed Mac app. It can manage the local server, inspect models, prepare plugins, and apply configuration. Begin with the CLI shipped by the app you are testing; a command from another installation can give misleading version and server results.

Establish a working connection

mellow version
mellow doctor --redact
mellow serve
mellow status
mellow list

doctor checks installation and server conditions. It is useful before changing settings because it can identify duplicate app bundles and CLI/app version skew. Add --json for automation or --verify-signatures when you specifically need signature checks. A diagnostic exit code and report describe installation health, not the quality of a model's answers.

Install the command through the app's Command Line Tool control. Search that exact title in Mellow settings if the navigation has changed. If your shell cannot find it, check command -v mellow and your PATH before installing a second copy.

Server lifecycle

Plain serve is a startup action, not a persistent supervisor. --supervise remains running; use it only where restarting the app after a deliberate quit is intended. --yes skips the network-exposure prompt and belongs in scripts only when that exposure is already intentional.

The CLI reads MELLOW_PORT before saved server configuration. With neither present, the normal server default is 1337. Use the address displayed by the running app when verifying a particular build.

Choose and inspect a model

mellow list
mellow show MODEL_ID
mellow pull PUBLISHER/MODEL_REPOSITORY
mellow run MODEL_ID

Replace MODEL_ID with an identifier returned by list. show reports the selected bundle's metadata; it does not validate every capability advertised by the model. pull downloads a repository, while run starts an interactive conversation with an available model.

Model directory resolution checks MELLOW_MODELS_DIR, the app's saved folder bookmark, and its shared CLI setting before existing default locations. The current default is ~/MLXModels; existing older folders may be discovered for continuity. Use doctor to establish which path actually resolved instead of assuming that a download went into a particular folder.

Measure a real request

mellow bench --model MODEL_ID --prompt-tokens 1024,8192 --runs 3 --json bench.json

Benchmark output includes timing and hardware context. Keep the model bundle, app build, generation options, and cache state with the result. First-load timing, warm generation, prefill, and decode measure different work. A quick benchmark cannot certify tool calling, image handling, or multi-turn stability.

Connect an MCP client

Run mellow mcp as the command in a client's stdio server configuration. It bridges the client's MCP connection to Mellow's local HTTP tools. Start the server first and verify the tools you intend to expose.

When network exposure requires authentication, pass --access-key or set MELLOW_MCP_ACCESS_KEY through the client's secret configuration. Avoid putting a real key into a shared configuration example. An empty tool list can reflect enabled tools and external-exposure policy; it is not necessarily a transport failure.

Manage capabilities

Registry availability depends on the configured service. Review a plugin's behavior and requested access before enabling it for an agent. For authoring and packaging, follow Plugin development.

Reproduce configuration safely

mellow config export -o mellow.yaml
mellow config schema --format json
mellow config plan mellow.yaml
mellow config apply mellow.yaml

Read the plan before applying. --prune permits removal of managed items absent from the document; --yes confirms high-risk changes. Neither flag belongs in a default example that a new user might copy without understanding its scope. Credentials remain separate from exported configuration.

When something fails

Use mellow help for the installed build's command catalog. The coord namespace is a local coordination foundation, not a promise of a complete cloud deployment workflow.