> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/developer-docs/client-libraries/ilert-cli/migrate-to-ilert.md). # Migrate to ilert {% hint style="success" %} Note: if you have trouble following this guide, your ai agent can help you with that setup as well, simply provide this link: migrate-to-ilert.md to your agent and ask for guidance. {% endhint %} A migration is mostly reading one API and writing another: users, schedules, escalation policies, alert sources, services, status pages. That is work an agent does well — provided it knows how the two products differ, and provided nothing is created before you have seen the plan. The CLI gives it both. The command tree covers the full ilert API, `--dry-run` turns any change into a plan, and the bundled skills carry the mapping knowledge that is not visible from an API spec. {% hint style="info" %} This page assumes the CLI is installed and authenticated. If it is not, follow **Install** and **Authenticate** on the [ilert CLI](/developer-docs/client-libraries/ilert-cli.md) page first — it takes a single command each. {% endhint %} ## Overview of the expected migration steps 1. Have a coding/ai agent installed on your machine e.g. claude or codex 2. Install and authorize ilert-cli 3. Grab a read-only short-term token from your current provider 4. Place the current provider token in a credential-proxy, env variable or file 5. Start a new session with your agent 6. Reference the current provider token origin (first prompt suggestion below) 7. Prompt pointing at ilert-cli and your desire to migrate from current provider (second prompt suggestion below) 8. Wait for agent to gather context and ilert skills and to provide a migration plan 9. Adjust or approve plan execution 10. Verify imported resources with smoke test 11. Rotate used current provider token 12. Adjust your monitoring tools to switch to the new ilert integrationKeys 13. Make the cut over ## Before we invoke your agent, lets talk about handling your current provider's API key To read your existing configuration, the agent needs an API key for the provider you are migrating from. How you supply that key is your decision, but we recommend never typing it into a prompt. {% hint style="warning" %} If you are not running your agent like claude or codex from the shell but in the UI/apps, the below guide for environment variables will not work. In this case you have to place the SOURCE\_PROVIDER\_API\_KEY of your current provider in a file, explaining step 3 below is the same, except for reference the filename that you are using. Be sure to rotate the key immediately after the migration process is completed. {% endhint %} {% hint style="success" %} **Recommended** 1. Create a **read-only** key in your current provider, scoped to the minimum the migration needs, and give it a short expiry if the provider supports one. 2. Put it in an environment variable rather than in the conversation or a file: ```bash export SOURCE_PROVIDER_API_KEY="your-key" claude # or your favorite coding agent on the shell here ``` 3. Tell the agent how to reference it, instead of telling it the key: ``` Pass $SOURCE_PROVIDER_API_KEY from the environment to authorize with api. Never resolve, inspect, or reproduce its value — not in output, files, logs, commits, error messages, comments, or summaries. To confirm it's set, test presence only, never print it. If it's unset or empty, stop and tell me; don't substitute another key or ask me to paste one. ``` 4. **Revoke the key** in your current provider once the migration is complete. {% endhint %} {% hint style="warning" %} A key pasted into a prompt should be treated as disclosed. Prompts and agent transcripts are commonly stored and sent to third-party model providers, so rotate any credential that has been entered into a chat. {% endhint %} ## Let the agent pull the playbook and ask for a plan, not a migration The CLI ships migration playbooks as skills. The index lists what is bundled `ilert skills list`, including one for each on-call and status page provider we cover. They exist because the vocabulary collides in ways that look correct and route nothing. In most other tools, one object receives events, owns the escalation policy and holds the integration keys; in ilert that is an **Alert Source**, while an ilert **Service** is a business capability people subscribe to and which routes nothing. Likewise the actionable page is an ilert **Alert**, whereas an ilert **Incident** is the coordination record a level above it. An agent that skips the playbook maps both the obvious way and hands you a topology that pages no one. So, steer your agent into the right direction with a simple prompt: ``` The ilert CLI is installed, use it for anything alert- and incident-management related, see `ilert --help`. Migrate our on-call setup from to ilert using the ilert CLI. Find the relevant migration skills and plan every change with --dry-run and show me the full plan before you create anything. ``` The CLI backs that instruction up: destructive commands refuse to run unattended and exit `2` with a JSON envelope describing what they refused, so an agent should not quietly push through a change you did not approve. Work in the order the objects depend on each other — users and teams, then schedules, then escalation policies, then alert sources and services, then status pages — and review each stage before the next. A wrong escalation policy is cheap to fix while nothing points at it yet. The skills should already guide the agent to follow the correct order for each provider. {% hint style="success" %} Note that it is perfectly fine to port partial resources and their dependencies for a PoC with one or more teams first, to evaluate faster and gain confidence. Then port the rest over - to achieve that, just make sure to tell your agent when prompting the second prompt above. {% endhint %} ## Verify before you cut over After you followed up with your agent on the plan and finished importing your resources (as well as rotating that other providers token), we recommend a quick round of verifications before cutting over. ```bash ilert on-call now # who the new schedules actually page ilert schedules list -o json --jq '.[] | {id, name, type}' ilert event send -k -s "migration smoke test" ``` Integration keys are new on ilert, so every emitter has to be re-pointed — that step is manual by nature and is usually what decides the cut-over date. Fire a test event at each new source and confirm it reaches the intended responders before you switch traffic over. You dont have to run this manually, ask your agent to evaluate the smoke tests with you. {% hint style="info" %} ilert offers free migration assistance, including configuration review and setup help. Contact to get started. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ilert.com/developer-docs/client-libraries/ilert-cli/migrate-to-ilert.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.