Pulsar

Sponsor Pulsar

Pulsar CLI

Official Command Line Interface for the Pulsar Web Framework

Pulsar CLI provides project scaffolding, dependency management, development server, production builds, environment diagnostics, and advanced tooling designed for a clean and scalable developer experience.

Installation

Activate globally:

dart pub global activate pulsar_cli

After activation:

pulsar --help

Creating a project

Use the create command to launch the interactive project setup:

pulsar create

Or pass options directly to skip the prompts:

Option Description Values
--template Project template default, minimum, empty, todo
--use-cdn UI CDN integration none, tailwind, materialize
--icons Icon library none, material, bootstrap
-y Skip interactive prompts —

Example:

pulsar create my_app --template default --use-cdn tailwind --icons bootstrap

create generates a complete project including pubspec.yaml, analysis_options.yaml, and all template files. The analysis_options.yaml is pre-configured with custom_lint and pulsar_lint so static analysis works from the first run.

After creating a project, run:

cd my_app
pulsar get
pulsar serve

Dependencies and linting

Resolve dependencies and run the Pulsar linter in one step:

pulsar get

This command always runs dart pub get followed by dart run custom_lint. Running both together ensures the linter plugin is fully initialized after any dependency change — including after pulsar clean, after switching branches, or after a fresh clone.

Options

Option Description
--no-pub Skip dart pub get, only run linter

Use --no-pub when you know your dependencies are up to date and only want to re-run the linter:

pulsar get --no-pub

Why a dedicated command?

dart pub get and dart run custom_lint are related operations that are almost always needed together. pulsar get unifies them under a single command with clear progress output, so you never have to remember to run both manually.

Development server

Start the Pulsar dev server:

pulsar serve

Default port: 8080

Options

Option Description
--port, -p Custom port
--watch Enable file watching (live reload)

If --watch is disabled, you can control the server manually:

  • Press r → rebuild
  • Press q → quit

The dev server:

  • Compiles Dart to JavaScript
  • Extracts CSS to avoid FOUC
  • Serves assets from .dart_tool/pulsar
  • Supports SPA routing fallback
  • Injects live reload via WebSocket

Production build

Build for production:

pulsar build

Options

Option Description
--release Optimized build (default)
--no-release Development-level compilation

The build command:

  • Compiles Dart to optimized JS
  • Extracts precomputed CSS
  • Copies static assets
  • Generates SPA redirects (_redirects, vercel.json)
  • Outputs to build/

Environment diagnostics

Check the health of your Pulsar environment:

pulsar doctor

Example output:

  Pulsar Doctor
────────────────────────────────
✓ Dart SDK detected (0ms)
✓ Project structure valid (1ms)
✓ Dependencies resolved (2ms)
✓ .dart_tool directory present (0ms)
✓ pulsar_lint active and running (312ms)
✓ Routing base configuration looks valid (0ms)
✓ CSS extraction present (0ms)

────────────────────────────────
Score: 97 / 100 (Excellent)

6 checks passed

The doctor verifies:

  • Dart SDK availability
  • Project structure (web/, lib/, web/main.dart)
  • Resolved dependencies (pubspec.lock)
  • .dart_tool directory presence
  • pulsar_lint configuration and runtime status
  • Routing base (web/index.html)
  • Build hygiene (no stale build/ directory)
  • JS bundle size (if built)
  • CSS extraction status

Linter check

The doctor validates three things for pulsar_lint:

  1. pubspec.yaml declares custom_lint and pulsar_lint as dev dependencies
  2. analysis_options.yaml has the custom_lint plugin enabled
  3. dart run custom_lint runs without errors

If any of these fail, the doctor reports what is missing and suggests running pulsar get to restore the linter.

CI mode

pulsar doctor --ci

In CI mode:

  • Output is simplified to a single health score line
  • Exit code is 1 if the health score is below 70
  • Designed for GitHub Actions, GitLab CI, and similar pipelines

Clean

Remove internal build artifacts:

pulsar clean

This clears:

  • .dart_tool/pulsar
  • Compiled JS bundles
  • Extracted CSS artifacts

Useful when debugging build inconsistencies. After cleaning, run pulsar get to restore the linter and pulsar serve to recompile.

Typical workflow

# Create and set up a new project
pulsar create my_app
cd my_app
pulsar get

# Develop
pulsar serve

# After pulling changes or adding dependencies
pulsar get

# After cleaning build artifacts
pulsar clean
pulsar get
pulsar serve

# Check environment health
pulsar doctor

# Build for production
pulsar build

Architecture overview

Pulsar CLI is built around:

  • PulsarCompiler — centralized compilation pipeline, CSS extraction, output isolation inside .dart_tool/pulsar
  • DevServer — WebSocket live reload, manual rebuild mode, SPA fallback support
  • Doctor — environment validation, health scoring, CI-ready diagnostics, linter status check

Requirements

  • Dart SDK ^3.9.0
  • Modern browser

Libraries

pulsar_cli