npm package: @inforge/migrations-tools-cli
Description: Inforge's interactive CLI for side-effect-free Salesforce data operations by managing automation
Author: Inforge
Latest version: 1.7.1

# Inforge Migrations CLI (`imigrate`)

Inforge's interactive CLI tool that enables side-effect-free Salesforce data operations by managing validation rules, flows, and triggers.

## Features

- **Feature-grouped menu** - Organized by Automations, Backups, and Logs
- **Object search/filter** - Instantly find objects by typing instead of scrolling
- **Individual automation control** - Toggle specific automations with granular preview
- **Deactivate automation** (validation rules, flows, triggers) for clean data operations
- **Smart restore** with automatic state detection
- **Atomic operations** with automatic rollback on failure
- **Local backups** organized by org/object/type with operation type labels
- **Managed package awareness** - skip managed components gracefully
- **Full audit logging** for compliance
- **Beautiful interactive UI** powered by @clack/prompts

## Installation

```bash
# Install globally
npm install -g @inforge/migrations-tools-cli

# Or use npx (no installation required)
npx @inforge/migrations-tools-cli
```

## Prerequisites

- Node.js 18+
- Salesforce CLI (`sf` or `sfdx`) with at least one authenticated org
- Authenticated org: `sf org login web -a my-org`

Note: You'll select your org once when starting the CLI, and it will be used for all operations until you exit.

## Usage

Run the CLI:

```bash
imigrate
```

Or with npx:

```bash
npx @inforge/migrations-tools-cli
```

### Deactivate Automation

1. Select "Automations" > "Deactivate all"
2. Choose org, object (with search/filter), and automation type
3. Preview what will be affected
4. Confirm and execute
5. Backup saved automatically

### Manage Automations Individually

1. Select "Automations" > "Manage individually"
2. Choose org and object (with search/filter)
3. Choose automation type
4. Select specific items to toggle with checkboxes
5. Preview changes (activations and deactivations)
6. Confirm and execute
7. Backup saved automatically as "individual" operation

### Restore from Backup

1. Select "Automations" > "Restore"
2. Choose org, object (with search/filter), and automation type
3. Select backup from list (labels show "Bulk deactivate" or "Individual changes")
4. Preview smart detection (only restore what's needed)
5. Confirm and execute

### Manage Backups

Select "Backups" to view all backups organized by org/object/type.

### View Logs

Select "Logs" to see recent operations with status, timestamps, and details.

## Architecture

### Backup Structure

```
.backups/
├── my-org/
│   ├── Account/
│   │   ├── validation-rules/
│   │   │   ├── 2026-02-15_14-30-00-123.json
│   │   │   └── 2026-02-15_16-45-30-456.json
│   │   ├── flows/
│   │   │   └── 2026-02-15_15-00-00-789.json
│   │   └── triggers/
│   │       └── 2026-02-15_15-30-00-012.json
│   └── Contact/
│       └── validation-rules/
│           └── 2026-02-15_14-35-00-345.json
```

### Operation Logs

All operations are logged to `.logs/operations.log` (JSON format, one per line).

## Debugging

### Debug Logs

When errors occur, detailed error information including stack traces and API request/response data is automatically logged to `.logs/debug.log`. The error message will show you the exact path to the debug log file.

**Example error message:**
```
Failed to apply changes: The requested resource does not exist

Error details logged to: /path/to/your/project/.logs/debug.log
```

### Enable Verbose Debug Logging

For more detailed troubleshooting, enable debug mode to see all API calls and internal operations:

```bash
DEBUG=true imigrate
```

This will log detailed information about:
- API queries and their results
- Request/response payloads
- Internal state changes
- Detailed error contexts

Debug logs are written in JSON format with timestamps and structured context for easy analysis.

## Safety Features

### Atomic Operations

All deactivation and restore operations are **all-or-nothing**:
- If any error occurs, changes are automatically rolled back
- You'll never be left in a partial state

### Smart Restore

Before restoring, the tool checks the current org state:
- Only restores items that actually need it
- Skips items that are already in the desired state
- Shows a preview of exactly what will change

### Managed Package Awareness

The tool identifies managed package components:
- Shows managed items in preview with counts
- Skips them during deactivation (can't be modified)
- Clearly explains why they're skipped

### Preview Before Action

Every operation shows a detailed preview:
- What will be affected
- What will be skipped (managed packages)
- Exact counts

You must confirm before any changes are made.

## Development

### Setup

```bash
git clone <repo>
cd migrations-cli
npm install
```

### Run in dev mode

```bash
npm run dev
```

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

## Supported Automation Types

### V1 (Current)
- Validation Rules
- Flows
- Triggers

### Future
- Process Builder
- Workflow Rules
- Duplicate Rules
- Matching Rules

## Contributing

Contributions welcome! Please open an issue or PR.

## License

MIT