Setting Up a Project

Run miso init to set up Miso in your project.

This creates a miso.json configuration file in the current directory. Miso will try to assume its own default configuration, but will ask you to confirm during miso init to make sure you’re both on the same page.

Choosing Your Repo Type

Basic Setup:

or, for more advanced setups:

Single Project

Miso works exactly as you’d expect — one miso.json at the root, one scripts/ folder, run commands from anywhere in the project, and they’ll respond the same way npm, bun, pnpm, etc would.

Monorepo

During Init, If you select Monorepo, miso will ask for your workspace glob patterns. This defaults to apps/*, packages/* which covers the most common monorepo layouts. Miso will add a workspaces field to your root package.json using the patterns you provide, and create the base workspace directories for you (if they don’t already exist)

Simple Mode

If miso init doesn’t detect an existing JavaScript project (no package.json or lockfile), it offers an additional option:

miso could not detect an existing javascript project.
 
  ❯ Create new project
    Run in simple mode (scripts only, no package manager)

Selecting Run in simple mode lets you use miso’s script runner, TUI, env validation, and task orchestration in any project — Go, Python, Rust, or anything else, without passing through commands to a package manager like bun, pnpm, etc.

See Simple Mode for the more details.

Running Commands from Anywhere

You can run Miso commands from any subdirectory within your project. Miso walks up the directory tree to find your miso.json at the root.

my-monorepo/
├── miso.json
├── package.json
├── apps/
│   ├── api/
│   │   └── scripts/
│   │       └── build.sh
│   └── web/
│       └── scripts/
│           └── build.sh
└── packages/
    └── ui/
        └── scripts/
            └── build.sh

Running Workspace Scripts from Root

In a monorepo, use @workspace/script syntax to target a specific workspace’s scripts folder from anywhere:

miso @api/build           # runs apps/api/scripts/build.sh in apps/onboarding/
miso @web/build           # runs apps/web/scripts/build.sh in apps/web/
miso @ui/build            # runs packages/ui/scripts/build.sh in packages/ui/

Automatic Scoping from Inside a Workspace

When you’re already inside a workspace directory, Miso automatically scopes to that workspace — no special syntax needed:

cd apps/web
miso build    # automatically resolves to apps/web/scripts/build.sh