Migrate from Insomnia

​

Why Migrate to Auk?

​

Migration Overview

1. Export data from Insomnia
2. Import into Auk workspace
3. Configure environments
4. Set up Git sync (optional)
5. Verify and test

​

Step 1: Export from Insomnia

​

Export All Data

​

Export Individual Collections

1. Right-click on collection in sidebar
2. Select “Export”
3. Choose format: “Insomnia v4 (JSON)”
4. Save file

​

Step 2: Prepare Auk Workspace

​

Create Workspace

1. Launch Auk
2. Create a new workspace
3. Choose storage location
4. Optionally configure Git sync

​

Plan Structure

Auk Workspace
├── Collections/
│   ├── API-Project-1/
│   ├── API-Project-2/
│   └── Testing/
└── Environments/
    ├── Development
    ├── Staging
    └── Production

​

Step 3: Import into Auk

​

Import Process

​

What Gets Imported

• ✅ Collections and folders
• ✅ Requests (all types)
• ✅ Request headers
• ✅ Request bodies
• ✅ Query parameters
• ✅ Authentication settings
• ✅ Environments
• ✅ Environment variables
• ✅ Base environments

• ❌ Plugins (Insomnia-specific)
• ❌ Themes (use Auk themes)
• ❌ Workspace settings (configure in Auk)
• ❌ Sync settings (use Git sync)

​

Step 4: Configure Environments

​

Review Imported Environments

1. Click “Environments” in sidebar
2. Review imported environments
3. Check variable names and values

​

Set Secret Values

1. Open each environment
2. Find variables marked as secret
3. Enter actual secret values
4. Mark as “Secret” in Auk
5. Save environment

​

Environment Mapping

​

Step 5: Verify Migration

​

Check Collections

• All collections imported
• Folder hierarchy correct
• Request names preserved
• Request order maintained

• URLs correct
• HTTP methods correct
• Headers present
• Bodies intact
• Authentication configured

​

Check Environments

• All variables imported
• Variable names correct
• Values correct
• Secret variables marked

• Variables resolve in requests
• Environment switching works
• Nested variables work

​

Test Requests

1. Select appropriate environment
2. Send test requests
3. Verify responses
4. Check authentication
5. Test variable substitution

​

Feature Mapping

​

Insomnia Features → Auk Equivalents

​

Variable Syntax

{{ _.baseUrl }}/{{ _.apiVersion }}/users

<<baseUrl>>/<<apiVersion>>/users

​

Template Tags

{% now 'iso-8601' %}

const now = new Date().toISOString();
pw.env.set("timestamp", now);

<<timestamp>>

​

Common Issues and Solutions

​

Issue: Import Fails

1. Verify file is valid JSON
2. Check file is Insomnia v4 format
3. Try exporting again from Insomnia
4. Check file size (large files may timeout)
5. Try importing individual collections

​

Issue: Variables Not Resolving

1. Check environment is active
2. Verify variable names match
3. Check variable is defined in environment
4. Remove _. prefix if present

​

Issue: Authentication Not Working

1. Check auth type is supported
2. Verify credentials are correct
3. Re-configure authentication
4. Test with simple request first

​

Issue: Template Tags Not Working

1. Manually convert to pre-request scripts
2. Use Auk’s built-in functions
3. Check documentation for equivalents

​

Issue: Missing Environments

1. Check if environments were in export
2. Try exporting “All Data” instead of workspace
3. Manually recreate missing environments
4. Check import summary for errors

​

Migration Checklist

​

Pre-Migration

• List all Insomnia workspaces
• Identify all collections
• Identify all environments
• Document secret variables
• Document template tags used
• Create backup of Insomnia data

​

Export Phase

• Export all data from Insomnia
• Or export individual workspaces
• Save export files
• Verify exports are complete

​

Import Phase

• Create Auk workspace
• Import Insomnia export
• Review import summary
• Set secret variable values
• Convert template tags
• Test sample requests

​

Verification Phase

• All collections present
• All requests working
• All environments configured
• Variables resolving correctly
• Authentication working
• Template tags converted

​

Post-Migration

• Configure Git sync (if needed)
• Share with team
• Update documentation
• Train team members
• Archive Insomnia data

​

Advanced Migration

​

Migrating Plugins

1. Request Chaining
   • Use Auk’s test scripts
   • Extract values from responses
   • Set as environment variables
2. Custom Authentication
   • Implement in pre-request scripts
   • Use Auk’s auth types
   • Or use custom headers
3. Data Generators
   • Use pre-request scripts
   • JavaScript functions
   • Faker.js (if needed)

​

Migrating Design Documents

1. Export OpenAPI spec from Insomnia
2. Import OpenAPI spec into Auk
3. Auk generates requests from spec
4. Review and adjust as needed

​

Batch Migration

1. Export each workspace separately
2. Create corresponding Auk workspaces
3. Import each export into its workspace
4. Or create one Auk workspace with folders

​

Team Migration

​

Communication Plan

• Announce migration timeline
• Explain benefits
• Provide training materials
• Set expectations

• Daily check-ins
• Support channel (Slack/Teams)
• Document issues
• Share solutions

• Gather feedback
• Address concerns
• Continuous support
• Celebrate success

​

Training Materials

1. Quick Start Guide
   • Install Auk
   • Import data
   • Basic usage
2. Feature Comparison
   • Insomnia vs Auk
   • What’s different
   • What’s better
3. Video Tutorials
   • Screen recordings
   • Common workflows
   • Tips and tricks

​

Cost Comparison

Team Size: 10 users
Plan: Team ($5/user/month)
Annual Cost: 10 × $5 × 12 = $600/year

Team Size: 10 users
Plan: Free (local-first)
Annual Cost: $0/year

Optional Git Hosting:
- GitHub Free: $0/year
- GitLab Free: $0/year
- Self-hosted: One-time setup

Total Annual Cost: $0/year

​

Next Steps

​

Support

• Documentation: auk.mamahuhu.dev
• GitHub Issues: github.com/mamahuhu-io/auk/issues
• Community: Join our discussions