Revit CLI

A powerful command-line interface for communicating with Autodesk Revit, designed to extract, parse, and manipulate building data efficiently.

Features

• 🏗️ Revit Integration: Direct communication with Revit API for data extraction
• 🔌 Plugin System: Extensible architecture supporting 100+ tools
• 📊 Data Processing: Extract elements, parameters, and geometry data
• 📁 Multiple Formats: Support for JSON, CSV, and XML output
• ⚙️ Configuration Management: Flexible configuration system
• 🎯 TypeScript: Full type safety and modern development experience

Installation

Prerequisites

• Node.js 18+
• npm 8+
• Autodesk Revit 2025+ (with API access)
• .NET 8.0 Runtime

Quick Setup (Recommended)

# Clone the repository
git clone <repository-url>
cd revit-cli

# Install dependencies
npm install

# Build and deploy everything to Revit
npm run build:full

This will:

1. Build the CLI
2. Build the Revit Add-in
3. Deploy both to the Revit Add-ins folder
4. Install all necessary dependencies

Install from npm

npm install -g revit-cli

Development Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Deploy CLI only to Revit folder
npm run build:deploy

Deployment

The CLI can be deployed to the Revit Add-ins folder for easy access:

Deployment Options

# Deploy CLI only
npm run build:deploy

# Deploy both CLI and Revit Add-in
npm run build:full

# Deploy Revit Add-in only
cd revit-addin
powershell -ExecutionPolicy Bypass -File build.ps1 -Deploy

# Deploy CLI with Revit Add-in build
cd revit-addin
powershell -ExecutionPolicy Bypass -File build.ps1 -Deploy -DeployCli

Deployed Location

After deployment, the CLI is available at:

%APPDATA%\Autodesk\Revit\Addins\2025\revit-cli\

Using Deployed CLI

# Navigate to the deployed location
cd "%APPDATA%\Autodesk\Revit\Addins\2025\revit-cli"

# Use the batch launcher
.\revit.bat --help
.\revit.bat test-connection

# Or use PowerShell launcher (recommended)
.\revit.ps1 info
.\revit.ps1 extract

# Or use Node.js directly
node cli.js info

Quick Start

Simplified Commands (Recommended)

For easier usage, you can use the wrapper scripts:

# Windows Batch File
.\revit.bat info                    # Get project information
.\revit.bat extract                 # Extract elements
.\revit.bat test-connection         # Test connection to Revit
.\revit.bat --help                  # Show help

# PowerShell Script (recommended)
.\revit.ps1 info                    # Get project information
.\revit.ps1 extract                 # Extract elements
.\revit.ps1 test-connection         # Test connection to Revit
.\revit.ps1 --help                  # Show help

Global Installation (Optional)

To use revit command globally from anywhere:

# Run the installation script
.\install-cli.ps1 -AddToPath

# After installation, restart your terminal and use:
revit info
revit extract
revit --help

1. Test Revit Connection

revit-cli test-connection
# or using wrapper:
.\revit.ps1 test-connection

2. Get Project Information

revit-cli info
# or using wrapper:
.\revit.ps1 info

3. List Available Categories

revit-cli categories
# or using wrapper:
.\revit.ps1 categories

4. Extract Elements

# Extract all elements
revit-cli extract
# or using wrapper:
.\revit.ps1 extract

# Extract specific categories
revit-cli extract -c "Walls,Doors,Windows"
# or using wrapper:
.\revit.ps1 extract -c "Walls,Doors,Windows"

# Extract with specific parameters
revit-cli extract -p "Name,Type,Level" -f json -o output.json
# or using wrapper:
.\revit.ps1 extract -p "Name,Type,Level" -f json -o output.json

# Include geometry data
revit-cli extract -g -f csv -o elements.csv
# or using wrapper:
.\revit.ps1 extract -g -f csv -o elements.csv

Available Commands

Core Commands

• revit-cli list - List all available tools
• revit-cli config - Manage configuration settings
• revit-cli test-connection - Test Revit API connection

Data Extraction

• revit-cli extract - Extract elements from Revit model
• revit-cli categories - List available Revit categories
• revit-cli info - Get project information
• revit-cli parse - Parse and analyze data files

Plugin Management

• revit-cli plugins - List installed plugins
• revit-cli plugin install <name> - Install a plugin
• revit-cli plugin remove <name> - Remove a plugin

Configuration

The CLI uses a configuration file located at ~/.revit-cli/config.json:

{
  "revit": {
    "apiUrl": "http://localhost:8080",
    "timeout": 30000,
    "retries": 3
  },
  "output": {
    "defaultFormat": "json",
    "defaultPath": "./output"
  },
  "logging": {
    "level": "info",
    "file": "~/.revit-cli/logs/cli.log"
  }
}

Configuration Commands

# View current configuration
revit-cli config show

# Set a configuration value
revit-cli config set revit.apiUrl "http://localhost:9090"

# Edit configuration interactively
revit-cli config edit

# Reset to defaults
revit-cli config reset

Plugin Development

The CLI supports a powerful plugin system for extending functionality.

Plugin Structure

plugins/
├── my-plugin/
│   ├── plugin.json
│   ├── index.ts
│   └── tools/
│       ├── tool1.ts
│       └── tool2.ts

Creating a Plugin

1. Create plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom Revit tools",
  "author": "Your Name",
  "keywords": ["revit", "custom"],
  "dependencies": {}
}

2. Create index.ts:

import { Plugin, Tool, ToolContext } from '@/types';
import metadata from './plugin.json';

const myTool: Tool = {
  name: 'my-tool',
  description: 'My custom tool',
  category: 'custom',
  async execute(options, context: ToolContext) {
    const { logger, revitConnector } = context;
    logger.info('Executing my custom tool...');
    // Tool implementation
  }
};

const plugin: Plugin = {
  metadata,
  tools: [myTool],
  async initialize(context: ToolContext) {
    context.logger.debug('My plugin initialized');
  }
};

export default plugin;

Tool Options

Tools can define command-line options:

const tool: Tool = {
  name: 'example',
  description: 'Example tool with options',
  options: [
    {
      flags: '-f, --file <path>',
      description: 'Input file path'
    },
    {
      flags: '-v, --verbose',
      description: 'Verbose output',
      defaultValue: false
    }
  ],
  async execute(options, context) {
    if (options.verbose) {
      context.logger.info('Verbose mode enabled');
    }
    // Use options.file
  }
};

API Reference

RevitConnector

The RevitConnector provides methods for communicating with Revit:

// Test connection
const isConnected = await revitConnector.testConnection();

// Get project info
const projectInfo = await revitConnector.getProjectInfo();

// Extract elements
const result = await revitConnector.extractElements({
  categories: ['Walls', 'Doors'],
  parameters: ['Name', 'Type'],
  includeGeometry: true
});

// Get categories
const categories = await revitConnector.getCategories();

Logger

The logger provides consistent output formatting:

logger.info('Information message');
logger.success('Success message');
logger.warn('Warning message');
logger.error('Error message');
logger.debug('Debug message');

Examples

Extract Walls with Parameters

revit-cli extract \
  --categories "Walls" \
  --parameters "Name,Type,Height,Width,Area" \
  --format csv \
  --output walls.csv

Parse Extracted Data

revit-cli parse --file walls.csv --type csv --summary

Custom Configuration

# Set custom API endpoint
revit-cli config set revit.apiUrl "http://revit-server:8080"

# Set default output format
revit-cli config set output.defaultFormat "csv"

Current Status

✅ FULLY OPERATIONAL - All core functionality working perfectly!

Recent Fixes (January 2025)

• Connection Issues Resolved: CLI successfully connects to Revit API server
• Category Parsing Fixed: Now retrieves and displays all 385 Revit categories with element counts
• API Response Handling: Enhanced parsing for complex nested response structures
• Debug Logging: Comprehensive logging system for troubleshooting
• Modular Architecture: Clean, maintainable codebase with professional CLI experience

Verified Working Features

• ✅ Connection testing (revit.ps1 test-connection)
• ✅ Category listing (revit.ps1 categories) - Shows 385 categories with counts
• ✅ Project information retrieval (revit.ps1 info)
• ✅ Element extraction (revit.ps1 extract)
• ✅ Configuration management
• ✅ Plugin system
• ✅ Multiple output formats (JSON, CSV, XML)

Troubleshooting

Common Issues

1. Connection Failed

   • Ensure Revit is running with an active document
   • Start the API server from within Revit (via the add-in)
   • Check that API endpoint is http://localhost:8080 (no /api suffix)
   • Verify firewall settings

2. "No Active Document Found"

   • Open a Revit project file (.rvt)
   • Ensure the document is the active view
   • The API server requires an active document to function

3. Plugin Not Found

   • Check plugin directory structure
   • Verify plugin.json format
   • Ensure proper exports in index.ts

4. Permission Errors

   • Run with appropriate permissions
   • Check file/directory access rights

Debug Mode

# Enable debug logging (already enabled by default)
revit-cli config set logging.level "debug"

# View logs
tail -f ~/.revit-cli/logs/cli.log

# Test connection with detailed output
.\revit.ps1 test-connection

# View categories with debug info
.\revit.ps1 categories

Setup Verification

1. Verify Revit Add-in Installation:

   Check: %APPDATA%\Autodesk\Revit\Addins\2025\RevitApiServer.addin

2. Test CLI Deployment:

   cd "%APPDATA%\Autodesk\Revit\Addins\2025\revit-cli"
   .\revit.ps1 --help

3. Verify API Server:

   • Open Revit 2025
   • Open a project file
   • Look for "Revit API Server" in the Add-ins tab
   • Start the server if not already running

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Development Commands

# Run tests
npm test

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Build project
npm run build

# Build and deploy CLI to Revit Add-ins folder
npm run build:deploy

# Build and deploy both CLI and Revit Add-in
npm run build:full

# Watch mode
npm run dev

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review existing issues

Built with ❤️ for the Revit community