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

Tolaria’s command-line interface is defined entirely by npm scripts in 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 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, this maps directly to the vite command.

pnpm dev

This hot-reloads your changes instantly as you edit files in the src/ directory, including the entry point at 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.

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.

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.

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.

# 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 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.

pnpm tauri

This command builds the native desktop binary according to the configuration in 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.

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.

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.

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 — Contains the central "scripts" section (lines 7–24) where all CLI commands are defined, along with the dependency manifest.
• vite.config.ts — Configures the Vite development server and build pipeline used by pnpm dev and pnpm build.
• 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 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 and starts the development server at http://localhost:5173, hot-reloading changes from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}