revit-cli/README.md

A scalable CLI tool for Revit communication and data manipulation

# 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)
```bash
# 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

```bash
npm install -g revit-cli
```

### Development Setup
```bash
# 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

```bash
# 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
```cmd
# 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:

```bash
# 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:

```powershell
# 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

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

### 2. Get Project Information

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

### 3. List Available Categories

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

### 4. Extract Elements

```bash
# 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`:

```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

```bash
# 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**:

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

2. **Create index.ts**:

```typescript
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:

```typescript
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:

```typescript
// 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:

```typescript
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

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

### Parse Extracted Data

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

### Custom Configuration

```bash
# 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

```bash
# 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**:
   ```bash
   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

```bash
# 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**