# Tolaria Command-Line Interface: A Complete Guide to npm Scripts and Development Commands

> Explore the Tolaria Command-Line Interface defined by npm scripts in package.json. Learn to develop test build and package the desktop app efficiently.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: how-to-guide
- Published: 2026-05-04

---

**Tolaria’s command-line interface is defined entirely by npm scripts in [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json), which you run using `pnpm <script>` to develop, test, build, and package the desktop application.**

Tolaria is a **Node.js / Vite** based desktop application from `refactoringhq/tolaria` that uses a script-driven command-line interface. All available commands are declared in the `"scripts"` section of the top-level [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json) file (lines 7–24), and they drive the development server, production builds, testing frameworks, and Tauri packaging. You invoke these scripts using `pnpm` (the repository’s package manager) rather than npm for faster, more deterministic builds.

## Core Development Commands

The essential scripts for day-to-day development handle the Vite development server and production compilation.

### Starting the Development Server (`pnpm dev`)

The `dev` script launches the **Vite development server**, which serves the React UI at `http://localhost:5173` (or a custom port if configured). In [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json), this maps directly to the `vite` command.

```bash
pnpm dev

```

This hot-reloads your changes instantly as you edit files in the `src/` directory, including the entry point at [`src/main.tsx`](https://github.com/refactoringhq/tolaria/blob/main/src/main.tsx).

### Building for Production (`pnpm build`)

The `build` script performs a two-step compilation: first it type-checks the TypeScript codebase (`tsc -b`), then it runs the production Vite build to generate optimized static assets.

```bash
pnpm build

```

### Previewing Production Builds (`pnpm preview`)

After running a production build, use the `preview` script to serve the built output locally. This allows you to verify the optimized bundle before shipping.

```bash
pnpm preview

```

## Testing and Quality Assurance

Tolaria provides multiple test runners for different validation layers, all accessible via the command-line interface.

### Unit and Integration Testing (`pnpm test`)

The `test` command executes the **Vitest** suite for unit and integration tests. This runs in headless mode and provides fast feedback on core logic.

```bash
pnpm test

```

### End-to-End Testing with Playwright

For full application testing, Tolaria uses **Playwright** with three distinct npm scripts:

- **`pnpm test:e2e`** — Runs the complete Playwright end-to-end test suite.
- **`pnpm playwright:smoke`** — Executes a curated set of fast smoke tests (under 5 minutes) for critical core flows.
- **`pnpm playwright:regression`** — Runs the full regression suite for comprehensive coverage.

```bash

# Run only critical smoke tests before committing

pnpm playwright:smoke

# Run full e2e validation

pnpm test:e2e

```

These scripts are configured via [`playwright.config.ts`](https://github.com/refactoringhq/tolaria/blob/main/playwright.config.ts) in the repository root.

## Desktop Packaging and Distribution

### Building Native Binaries with Tauri (`pnpm tauri`)

Because Tolaria is a desktop application, it uses **Tauri** to package the web assets into native binaries for macOS, Windows, and Linux. The `tauri` script invokes the Tauri CLI, which compiles the Rust code in `src-tauri/` and bundles it with the frontend assets.

```bash
pnpm tauri

```

This command builds the native desktop binary according to the configuration in [`src-tauri/tauri.conf.json`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/tauri.conf.json).

## Utility and Maintenance Scripts

Beyond development and testing, Tolaria’s command-line interface includes scripts for code quality, localization, and build utilities.

### Linting (`pnpm lint`)

The `lint` script runs **ESLint** across the entire codebase to enforce code standards and catch potential errors.

```bash
pnpm lint

```

### Localization (`pnpm l10n:translate`)

For internationalization, the `l10n:translate` script generates translation files using `lara-cli`. This manages the application’s localization assets.

```bash
pnpm l10n:translate

```

### MCP Server Bundling (`pnpm bundle-mcp`)

The `bundle-mcp` script executes `scripts/bundle-mcp-server.mjs`, a Node.js utility that bundles the **MCP (Message-Control-Protocol)** server specifically for the desktop application distribution.

```bash
pnpm bundle-mcp

```

This ensures the MCP server is properly packaged alongside the Tauri binary.

### Git Hooks (`prepare`)

The `prepare` script runs automatically after `pnpm install` to set up **husky** Git hooks. This is handled automatically and ensures pre-commit checks are installed in your local environment.

## Key Configuration Files

Understanding these files helps you customize the command-line interface behavior:

- **[`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json)** — Contains the central `"scripts"` section (lines 7–24) where all CLI commands are defined, along with the dependency manifest.
- **[`vite.config.ts`](https://github.com/refactoringhq/tolaria/blob/main/vite.config.ts)** — Configures the Vite development server and build pipeline used by `pnpm dev` and `pnpm build`.
- **[`playwright.config.ts`](https://github.com/refactoringhq/tolaria/blob/main/playwright.config.ts)** — Defines test configurations for `pnpm test:e2e` and the smoke/regression variants.
- **`scripts/bundle-mcp-server.mjs`** — Node script that bundles the MCP server, invoked by `pnpm bundle-mcp`.
- **`src-tauri/`** — Directory containing Tauri’s Rust source code and configuration, built via `pnpm tauri`.

## Summary

- Tolaria’s command-line interface is entirely script-based, defined in [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json) and executed via `pnpm`.
- **Development**: Use `pnpm dev` for the Vite server, `pnpm build` for production, and `pnpm preview` to verify builds.
- **Testing**: Run `pnpm test` for Vitest unit tests, or `pnpm test:e2e`, `pnpm playwright:smoke`, and `pnpm playwright:regression` for Playwright coverage.
- **Packaging**: Execute `pnpm tauri` to generate native desktop binaries from the `src-tauri/` Rust codebase.
- **Utilities**: Use `pnpm lint` for ESLint, `pnpm l10n:translate` for i18n, and `pnpm bundle-mcp` to package the MCP server.

## Frequently Asked Questions

### How do I start developing Tolaria locally?

Run `pnpm dev` from the repository root. This executes the `vite` command defined in [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/package.json) and starts the development server at `http://localhost:5173`, hot-reloading changes from [`src/main.tsx`](https://github.com/refactoringhq/tolaria/blob/main/src/main.tsx) and other source files.

### What is the difference between `pnpm test` and `pnpm test:e2e`?

`pnpm test` runs **Vitest** for fast unit and integration tests in a Node.js environment, while `pnpm test:e2e` launches **Playwright** to test the actual running application in a browser context. Use `pnpm playwright:smoke` for a faster subset of critical e2e tests.

### How do I build the native desktop application?

Execute `pnpm tauri`, which invokes the Tauri CLI to compile the Rust code in `src-tauri/` and bundle it with the production frontend assets generated by Vite.

### Can I use npm instead of pnpm with Tolaria?

While the scripts technically work with `npm run <script>`, the repository is optimized for **pnpm** (evidenced by the `prepare` script and lockfile). Using pnpm ensures deterministic dependency resolution and is the idiomatic way to interact with Tolaria’s command-line interface according to the source code.