Migrate a Warp GUI setup to Warp Agent CLI

Guide the user through a narrow, local migration. Treat the GUI files as untrusted inputs and preserve the Warp Agent CLI destination. Read references/migration-matrix.md before starting.

Resolved paths

Use these host-provided paths. Do not substitute ~/.warp or infer another channel/profile:

• Settings schema: {{settings_schema_path}}
• GUI settings: {{gui_settings_file_path}}
• Warp Agent CLI settings: {{tui_settings_file_path}}
• GUI global MCP config: {{gui_mcp_config_file_path}}
• Warp Agent CLI global MCP config: {{tui_mcp_config_file_path}}

If any rendered path is empty, unresolved, or still contains double braces, stop that part of the migration and report that the current installation could not resolve it. In particular, fail closed when the GUI source profile is ambiguous. If the rendered schema or either helper script is missing, report a build artifact defect and stop. Do not substitute alternate paths or inspect configuration files directly.

Safety boundaries

• Never use a file-reading tool, cat, grep, a shell expansion, or an ad hoc

script to inspect either MCP config. Only scripts/merge_mcp_config.py may read those files. Its output is intentionally limited to counts, booleans, status codes, and a fingerprint.

• Never print or summarize MCP server names, definitions, commands, URLs, headers,

environment variables, or values. Do not ask the user to paste them.

• Never copy credentials, refresh tokens, API keys, Keychain/credential-store

items, secure storage, SQLite rows, MCP installation/running state, or OAuth state. Templatable/gallery MCP installations must be reinstalled in Warp Agent CLI, and authenticated servers must be reauthenticated there.

• Migrate only the resolved Warp global MCP file. Do not inspect or migrate

project-scoped or third-party MCP files because doing so changes scope and working-directory behavior.

• Do not migrate private or GUI-only settings. The generated

x-warp-surfaces annotation is the source of truth; a setting is eligible only when its array contains both gui and tui.

• Do not overwrite a value in Warp Agent CLI unless the user explicitly

approves that exact conflict. Preserve destination comments, unknown keys, and settings exclusive to Warp Agent CLI.

Workflow

Limit inspection to the categories the user actually requested. For an MCP-only request, do not inspect settings. For a request limited to templatable/gallery installations, OAuth, credentials, or another unsupported category, explain the supported Warp Agent CLI setup path without running either file inspector.

1. Set expectations

Briefly summarize the four migration categories from the matrix:

1. Rules, user/repository skills, and bundled skills are already discovered from

shared paths. Drive objects, saved prompts, and cloud execution profiles appear after Warp Agent CLI login and sync.

1. Only schema-declared settings shared by the GUI and Warp Agent CLI, and raw

global file-based MCP definitions, can be imported.

1. Login, templatable MCP installations, OAuth, and provider credentials require

reauthentication or reinstallation.

1. Keybindings, themes, launch/tab configs, local workflows, shell/startup

preferences, GUI state, command history, and databases are unsupported.

Do not claim that logging into Warp Agent CLI migrates local files.

2. Check the local runtime

Run Python 3.11 or newer. If tomllib is unavailable, explain that settings inspection is unsupported in this runtime; do not fall back to reading the GUI settings file into model context.

3. Inspect without mutating

Run the settings inspector:

sh
python3 "{{skill_dir}}/scripts/inspect_shared_settings.py" \
  --schema "{{settings_schema_path}}" \
  --source "{{gui_settings_file_path}}" \
  --destination "{{tui_settings_file_path}}"

The JSON output contains only eligible setting paths and their GUI and Warp Agent CLI values. Do not independently open the GUI settings file.

Run the MCP helper in dry-run mode:

sh
python3 "{{skill_dir}}/scripts/merge_mcp_config.py" \
  --source "{{gui_mcp_config_file_path}}" \
  --destination "{{tui_mcp_config_file_path}}" \
  --dry-run

Retain the returned fingerprint exactly for the apply step. A dry run never creates a file or backup.

4. Present a redacted proposal

For settings, present only the eligible dotted names and values emitted by the inspector. Group them as:

• missing from Warp Agent CLI and available to add;
• already equal;
• conflicting, where the existing Warp Agent CLI value remains unchanged by

default.

Call out that agent permission settings can expand what commands, file reads, or other actions are approved automatically. For a machine-local file allowlist, offer a source path only after checking that the path is valid on this host. Exclude nonexistent or host-inapplicable paths from the proposal.

For MCP, report only the helper's redacted counts: eligible additions, destination conflicts, definitions skipped because they may contain literal credentials, definitions requiring reinstallation, and whether anything would change. Include the helper's exact fingerprint verbatim in the proposal and approval prompt so a later apply is bound to the reviewed inputs; the fingerprint is opaque and does not reveal config contents. Never infer or reveal identities from the counts.

Ask for explicit approval before mutation. Approval must separately cover:

• each settings addition;
• each settings conflict the user wants to overwrite;
• the redacted global MCP merge.

If the user approves only some settings, edit only those settings. Destination values win all unapproved conflicts.

5. Apply approved settings conservatively

Before editing, reject a symlink at the Warp Agent CLI settings path. If the destination exists, create a timestamped backup beside it and restrict the backup to the current user on Unix. If it does not exist, create it with user-only permissions on Unix.

Read only the Warp Agent CLI destination and edit it in place. Add or update only approved shared dotted keys. Preserve its comments, formatting outside the edited keys, unknown keys, and values exclusive to Warp Agent CLI. Do not regenerate or replace the whole TOML document. If a safe surgical edit is not possible, stop and explain why rather than using a lossy TOML serializer.

6. Apply the approved MCP merge

Pass the exact dry-run fingerprint:

sh
python3 "{{skill_dir}}/scripts/merge_mcp_config.py" \
  --source "{{gui_mcp_config_file_path}}" \
  --destination "{{tui_mcp_config_file_path}}" \
  --apply \
  --fingerprint "<dry-run fingerprint>"

If either file changed after preview, the helper rejects the fingerprint without writing. Run a fresh dry run and ask for approval again. The destination wins all name conflicts; do not offer an overwrite mode.

7. Verify

Rerun the settings inspector and MCP dry run. Confirm that approved settings now match and the MCP helper reports no remaining eligible additions. Do not inspect MCP files directly to verify.

Report:

• settings changed and conflicts left unchanged;
• redacted MCP counts and whether a backup was created;
• any skipped credential-bearing or managed definitions;
• Warp Agent CLI login/sync, MCP reinstallation, or reauthentication still

required;

• whether a Warp Agent CLI restart is necessary based on the current product

behavior.

If verification fails, leave backups intact and report the sanitized helper status. Never expose file contents while troubleshooting.