@writely/cli

Command-line interface and developer tools for the Writely blog platform. Provides powerful CLI commands for development, building, validation, and deployment of Writely blogs with comprehensive tooling and automation.

Features

• Development Server: Start a live preview server with hot reload and file watching
• Build System: Generate optimized static sites for production deployment
• Configuration Validation: Validate blog configuration and MDX content structure
• Link Checking: Find and report broken internal links with detailed analysis
• Analytics Integration: Built-in analytics and performance monitoring tools
• Interactive Setup: Guided blog initialization and configuration wizard
• Deployment Tools: Deploy to various platforms including Vercel, Netlify, and custom servers
• SEO Optimization: Generate sitemaps, RSS feeds, and meta tag optimization
• Content Management: Create, validate, and manage blog posts and pages
• Performance Monitoring: Track build times, bundle sizes, and optimization metrics

Installation

# Install globally for system-wide access
npm install -g @writely/cli

# Or use npx for one-time usage
npx @writely/cli --help

# Install as development dependency
npm install --save-dev @writely/cli

API

Commands

writely dev

Start the development server with live preview and hot reload capabilities.

writely dev [options]

Options:
  -p, --port <number>    Port to run on (default: 3000)
  -h, --host <string>    Host to run on (default: localhost)
  --no-open             Don't open browser automatically
  --config <path>       Path to blog configuration file
  --watch <patterns>    Custom file watching patterns
  --verbose             Enable verbose logging

writely build

Build the blog for production deployment with optimization and static generation.

writely build [options]

Options:
  -o, --output <dir>           Output directory (default: dist)
  --generate-sitemap          Generate sitemap.xml (default: true)
  --generate-rss              Generate RSS feed (default: true)
  --optimize-images           Optimize images during build
  --minify                    Minify output files
  --analyze                   Generate bundle analysis report

writely validate

Validate blog configuration, content structure, and MDX syntax.

writely validate [options]

Options:
  --config <path>       Path to blog configuration file
  --strict             Enable strict validation mode
  --fix                Automatically fix common issues

# Validates:
# - blog.json configuration schema
# - MDX file syntax and structure
# - Frontmatter consistency
# - Required directories and files
# - Theme configuration
# - SEO meta tag structure

writely broken-links

Check for broken internal links and provide detailed analysis.

writely broken-links [options]

Options:
  --config <path>       Path to blog configuration file
  --fix                 Attempt to fix broken links automatically
  --report <format>     Output format: json, csv, html (default: console)

# Scans all MDX files for internal links
# Reports broken or missing links with context
# Suggests fixes and alternatives
# Generates detailed link analysis report

writely init

Initialize a new Writely blog project with guided setup.

writely init <project-name> [options]

Options:
  --theme <theme>       Default theme (nova, atlas, pulse, prism, quantum, helix)
  --typescript         Use TypeScript configuration
  --git               Initialize git repository
  --install           Install dependencies automatically
  --template <name>   Use specific project template

writely new-post

Create a new blog post with proper frontmatter structure.

writely new-post <title> [options]

Options:
  --author <name>      Post author name
  --tags <tags>        Comma-separated tags
  --draft             Create as draft post
  --template <name>   Use specific post template

Programmatic Usage

import { program } from "@writely/cli";

// Access the CLI program directly
program.parse(process.argv);

// Use individual commands programmatically
import {
  validateBlog,
  buildBlog,
  startDevServer,
  checkBrokenLinks,
} from "@writely/cli";

// Validate blog configuration
const validationResult = await validateBlog("./blog.json", {
  strict: true,
  fix: false,
});

// Build blog for production
const buildResult = await buildBlog({
  config: blogConfig,
  outputDir: "./dist",
  generateSitemap: true,
  generateRss: true,
  optimizeImages: true,
  minify: true,
});

// Start development server
const server = await startDevServer({
  config: blogConfig,
  port: 3000,
  host: "localhost",
  open: true,
  watch: ["content/**/*", "public/**/*"],
});

// Check for broken links
const linkReport = await checkBrokenLinks("./blog.json", {
  fix: false,
  report: "json",
});

Configuration

The CLI reads configuration from blog.json in your project root. This file defines your blog's structure, theme, and behavior.

{
  "title": "My Blog",
  "description": "A beautiful blog built with Writely",
  "author": "Your Name",
  "url": "https://myblog.com",
  "language": "en",
  "theme": "nova",
  "seo": {
    "metatags": {
      "description": "My blog description",
      "keywords": "blog, writely, mdx"
    },
    "openGraph": {
      "type": "website",
      "siteName": "My Blog"
    }
  },
  "content": {
    "postsPerPage": 10,
    "defaultLayout": "post",
    "defaultAuthor": "Your Name",
    "defaultTags": ["blog", "writely"],
    "draftPosts": false
  },
  "build": {
    "outputDir": "dist",
    "generateSitemap": true,
    "generateRss": true,
    "optimizeImages": true,
    "minify": true
  },
  "development": {
    "port": 3000,
    "host": "localhost",
    "openBrowser": true,
    "watchPatterns": ["content/**/*", "public/**/*"]
  }
}

Development

Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.3.0 or higher
• pnpm (recommended) or npm

Setup

# Clone the repository
git clone https://github.com/WritelyBlog/writely.git
cd writely/packages/@writely/cli

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run in development mode
pnpm dev

Development Workflow

1. Install Dependencies: pnpm install
2. Build Package: pnpm build
3. Run Tests: pnpm test
4. Lint Code: pnpm lint
5. Watch Mode: pnpm dev

Scripts

• pnpm build - Build the CLI package with TypeScript compilation
• pnpm dev - Watch mode for development with hot reload
• pnpm lint - Run ESLint with TypeScript support
• pnpm clean - Clean build artifacts and temporary files
• pnpm test - Run unit and integration tests
• pnpm type-check - Run TypeScript type checking
• pnpm format - Format code with Prettier
• pnpm validate - Validate package configuration and dependencies

Architecture

The CLI package is structured for modularity, extensibility, and maintainability:

src/
├── index.ts              # Main CLI entry point and program setup
├── commands/             # Individual command implementations
│   ├── dev.ts           # Development server command with hot reload
│   ├── build.ts         # Build command with optimization
│   ├── validate.ts      # Configuration and content validation
│   ├── links.ts         # Link checking and analysis
│   ├── init.ts          # Project initialization wizard
│   └── new-post.ts      # Blog post creation utility
├── utils/               # Utility functions and helpers
│   ├── config.ts        # Configuration loading and validation
│   ├── files.ts         # File system operations and utilities
│   ├── validation.ts    # Content and schema validation
│   ├── logger.ts        # Logging and output formatting
│   └── analytics.ts     # Performance and usage analytics
├── types/               # TypeScript type definitions
│   ├── commands.ts      # Command-specific types
│   ├── config.ts        # Configuration types
│   └── utils.ts         # Utility function types
└── templates/           # Project and content templates
    ├── blog.json        # Default blog configuration
    ├── post.mdx         # Default post template
    └── project/         # Project structure templates

Core Components

Command System: Modular command architecture using Commander.js for extensible CLI functionality.

Configuration Management: Robust configuration loading with schema validation and environment-specific overrides.

File System Operations: Efficient file handling with streaming for large files and intelligent caching.

Validation Engine: Comprehensive validation of blog configuration, MDX content, and project structure.

Build Pipeline: Optimized build process with parallel processing, asset optimization, and static generation.

Development Server: Next.js-based development server with hot reload, file watching, and live preview.

Contributing

1. Fork Repository: Create a fork of the main repository
2. Create Feature Branch: git checkout -b feature/new-cli-command
3. Make Changes: Implement new functionality with proper TypeScript types
4. Add Tests: Include unit tests for new commands and utilities
5. Update Documentation: Update README and API documentation
6. Run Validation: Ensure all tests pass and code is properly formatted
7. Submit Pull Request: Create detailed pull request with description

Development Guidelines

• Follow TypeScript best practices with strict type checking
• Implement comprehensive error handling with helpful error messages
• Add unit tests for all new functionality
• Maintain backward compatibility for existing commands
• Use consistent logging and output formatting
• Follow the established code style and architecture patterns

License

MIT License - see LICENSE for details.