# Command auto-detection

When you add a project, Solo scans the folder to detect runnable commands automatically. This saves you from typing them all in by hand. You are free to skip this auto-detection altogether if you'd like.

## How detection works

After you select a project folder, Solo reads files in the project root, with a few targeted subdirectory checks such as Phoenix `assets/package.json` and root-level `.csproj` discovery, for example. Detected commands are presented in the [setup wizard](./creating-loading-projects.md) as suggestions. Some are pre-selected and some are offered but left unchecked. Before confirming, you can choose which suggestions to include and which included commands should auto-start. Add or edit commands after setup.

Detection runs automatically only when you first add a project that does not already have `solo.yml`. Editing files in the repo or editing `solo.yml` does not trigger automatic re-detection.

## Supported project types

### `package.json` scripts (npm / pnpm / yarn / bun)

Solo reads the `scripts` field in `package.json` and suggests matching priority scripts named `start`, `serve`, `build`, and `test`. When a `dev` script is present, Next.js, Nuxt, SvelteKit, Remix, and Astro replace its direct row with a framework-labeled package-manager command. Create React App detection currently suppresses a present `dev` script without adding a framework-specific replacement. Otherwise, a matching `dev` script is suggested directly. Solo also detects framework/tooling dependencies such as Next.js, Nuxt, SvelteKit, Remix, Astro, Vite, Create React App, Prisma, Drizzle, Storybook, Cypress, and Vitest.

Solo chooses the package-manager command from `packageManager` first, then lockfiles (`bun`, `pnpm`, `yarn`, `npm`), then falls back to npm.

### Procfile and Procfile.dev

If a `Procfile.dev` or `Procfile` is present at the project root, Solo reads it. Each valid, non-comment `name: command` entry becomes a command suggestion using the parsed name and shell command. Blank lines, comments, malformed entries, and entries with an empty name or command are skipped:

```
web: node server.js
worker: node worker.js
```

`Procfile.dev` takes priority over `Procfile`. Rails projects use Rails-specific detection for `Procfile.dev`, so generic Procfile suggestions may be skipped there.

### Makefile

Solo reads `Makefile`, `makefile`, or `GNUmakefile` targets and surfaces exact dev-relevant target names such as `dev`, `start`, `serve`, `run`, `watch`, `build`, `test`, `lint`, `check`, `typecheck`, `fmt`, `format`, `up`, `down`, `clean`, and `e2e`.

### Justfile

Solo reads `justfile`, `Justfile`, or `.justfile` recipes using the same dev-relevant target list. Private recipes prefixed with `_` are skipped.

### Taskfile (Task)

Solo reads `Taskfile.yml`, `Taskfile.yaml`, or `taskfile.yml` and surfaces tasks whose names match the dev-relevant target list.

When more than one of these task-runner files is present, Solo uses the first available runner in this order: Taskfile, Justfile, then Makefile.

### PM2 ecosystem files

For JSON/YAML PM2 configs (`ecosystem.json`, `process.json`, `pm2.json`, `ecosystem.yml`, or `ecosystem.yaml`), Solo reads the `apps` array and creates a command for each application entry. For JavaScript/TypeScript PM2 configs such as `ecosystem.config.js`, Solo does not parse the file; it suggests a single PM2 command to start that config file.

### Turborepo

Solo detects `turbo.json` and surfaces dev-relevant tasks from `tasks` or legacy `pipeline` as commands like `turbo run dev`.

### Nx

Solo detects `nx.json` and reads `targetDefaults` for dev-relevant target names, then suggests commands like `nx run-many --target=serve`.

### Other ecosystems

Solo also detects Laravel/PHP Composer, Rust/Cargo, Spring Boot, FastAPI, Flask, Django, generic Python, Rails, Go, .NET, Phoenix, Docker Compose, and some framework-specific workers or tooling when their expected files or dependencies are present. For a generic Python project with `requirements.txt` or `pyproject.toml`, Solo suggests `python main.py` when `main.py` exists; otherwise, if `app.py` exists, it suggests `python app.py`.

#### Laravel Herd

For Laravel projects, Solo looks for signals that Herd may already be serving the site: either a `herd.yml` file exists in the project, or Herd appears to be running on your Mac. When either signal is present, the `php artisan serve` suggestion is still offered but left unselected because a second development server may be redundant or may conflict. The suggestion's description explains why it wasn't preselected; check the box if you want it anyway.

## What gets suggested

Detection errs on the side of relevance — it prefers commands you'd run during active development over one-time setup tasks. Primary dev servers are often selected and marked for [auto-start](../commands/auto-start.md)/[auto-restart](../commands/auto-restart.md). Build, test, lint, formatter, migration, console, and GUI/tool commands may be offered without being selected or auto-started.

## Overriding or adding commands

Detected commands are just suggestions. In the setup wizard you can:

- **Uncheck** any detected command you don't want.
- **Choose Auto-start** for each included command.

The setup wizard does not let you rename suggestions or create arbitrary commands. After setup, use **Add command** in the project pane or sidebar to create a custom command, or open an existing command's menu and choose **Edit command...** to change its name or command. You can also remove commands from the sidebar. See [Adding & removing commands](../commands/adding-removing.md).

## If detection misses something

Some projects have unusual tooling or custom scripts. If Solo doesn't detect your commands:

1. Finish setup — or choose **I'll add my own commands** to skip its suggestions — then use **Add command** in the project pane or sidebar.
2. For future teammates, add the commands to `solo.yml` directly so they're always available.

## Re-running detection

Detection doesn't re-run automatically after initial setup. If you add new tooling later, add the new command manually via the sidebar or put it in `solo.yml`, or have your agent do it.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/projects/command-auto-detection