install-obs-migrate

name	install-obs-migrate
description	Use when obs-migrate is missing, doctor fails, the user asks how to install/set up the CLI, uvx/pip fails, Python is too old, extras are missing, or any other migration skill cannot run because the tool is not Ready — owns getting elastic-observability-migration installed and verified before connect/migrate skills proceed. Not for Grafana/Datadog/Elastic credentials (use connect-to-o11y-source).

Install and verify obs-migrate

Audience: operators who need a working obs-migrate before any migration. Other skills defer here so install guidance stays in one place.

Goal: get a Ready obs-migrate on this machine, then hand off to the skill the user actually wanted (connect-to-o11y-source, scan-o11y-environment, migrate skills, etc.). This skill is the only place that owns install commands, extras, and doctor gotchas — other skills must defer here instead of inventing install steps.

When to run this skill

Run before any other migration skill when any of these are true:

• obs-migrate / uvx … obs-migrate is not found
• obs-migrate doctor exits non-zero or is not Ready
• User asks how to install, which extra to use, or why Datadog/Grafana tooling is missing
• Default system Python is too old (common on macOS)

Do not use this skill for vendor/Elastic credentials — that is connect-to-o11y-source.

Supported platforms

• macOS and Linux only. Windows is not supported.
• Python 3.11+ required (3.11–3.13 is the tested range).
• Canonical docs: https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md → Install And Setup; README.md.

Step 0 — Detect current state

command -v uvx
command -v uv
command -v obs-migrate
python3 --version

Then run doctor with the recommended launcher first (uvx never needs obs-migrate on PATH). Only use the bare command when Step 0 already found it on PATH:

uvx --from 'elastic-observability-migration[all]' obs-migrate doctor
# or, if `command -v obs-migrate` succeeded above:
# obs-migrate doctor

Interpret:

Observation	Action
doctor prints Ready.	Install is done — hand off to the calling skill
command not found: obs-migrate and no uv/uvx	Install uv, then Step 1
command not found: obs-migrate but uvx works	The bare command was run without a launcher — re-run as uvx --from 'elastic-observability-migration[all]' obs-migrate …, .venv/bin/obs-migrate …, or after source .venv/bin/activate (spell the package out: PKG may be unset in this shell)
Python <3.11	Install/use a newer Python (pyenv, python.org, Homebrew python@3.12), then retry
doctor notes Datadog client not installed	Reinstall with [datadog] or [all] if the user needs Datadog API mode
doctor prints uv on PATH: no / uvx on PATH: no	Informational, not a blocker — no command shells out to uvx at runtime. Install uv only if you want the uvx launcher

Step 1 — Install uv (recommended path)

uv provides uv + uvx (no global pip required):

# https://docs.astral.sh/uv/getting-started/installation/
curl -LsSf https://astral.sh/uv/install.sh | sh
# then open a new shell or source the installer hint so uv/uvx are on PATH
command -v uvx

Step 2 — Choose the footprint

User needs	Extra	Notes
First-time / unsure / both sources	[all] (default)	Grafana + Datadog + tooling together
Grafana / Prometheus only	[grafana] or [all]	Base package already includes Grafana translation deps; [all] is still simplest
Datadog live API (--input-mode api)	[datadog] or [all]	File-mode Datadog works without the client; API mode needs datadog-api-client
Contributor / repo checkout	.[all,dev] via make sync	Not the operator path

Default recommendation: [all] via uvx so you are not blocked mid-migration by a missing extra.

Step 3 — Install and verify (operator path)

Recommended: ephemeral uvx (no venv)

PKG='elastic-observability-migration[all]'
# Optional pin: PKG='elastic-observability-migration[all]==1.0.0'
uvx --from "$PKG" obs-migrate doctor
uvx --from "$PKG" obs-migrate list-samples

Always prefix commands with uvx --from "$PKG" unless the user wants a persistent install.

Persistent venv

PKG='elastic-observability-migration[all]'
python3 -m venv .venv
.venv/bin/pip install "$PKG"
.venv/bin/obs-migrate doctor
# Or activate once per shell, then use bare obs-migrate:
# source .venv/bin/activate && obs-migrate doctor

A bare obs-migrate only resolves when its install location is on PATH — after source .venv/bin/activate, or a pipx install / uv tool install (next section). Otherwise use a launcher: .venv/bin/obs-migrate … (explicit path, no activate) or uvx --from "$PKG" ….

Both venv launchers are relative paths. If the user is not in the directory that holds .venv, they get no such file or directory instead of command not found — have them cd there or use the absolute path.

If the user hits command not found: obs-migrate, they most likely ran the bare command without one of those, in a shell where PKG may also be unset — so re-state the launcher with the package spelled out in full, e.g. uvx --from 'elastic-observability-migration[all]' obs-migrate doctor. See README.md → “If you see command not found”.

Persistent tool install (bare command, no prefix)

When the user wants obs-migrate on PATH for every shell:

uv tool install 'elastic-observability-migration[all]'
export PATH="$HOME/.local/bin:$PATH"
obs-migrate doctor

The shim lands in ~/.local/bin (uv tool dir --bin prints the real path). Do not drop the export: uv cannot change the PATH of the shell that invoked it, so without it the very next obs-migrate doctor fails with the same command not found — uv only prints a warning. Run uv tool update-shell once so later shells work without the export. pipx install 'elastic-observability-migration[all]' is equivalent. uv resolves against the newest Python present, so add --python 3.13 when the default is above the tested 3.11–3.13 range.

GitHub tag fallback (never @main)

Only if PyPI is unreachable:

PKG='elastic-observability-migration[all]@git+https://github.com/elastic/observability-migration-platform.git@v1.0.0'
uvx --from "$PKG" obs-migrate doctor

Repo checkout (contributors only — not the operator path)

make sync
uv run obs-migrate doctor
# or: .venv/bin/pip install -e ".[all,dev]"

Step 4 — Ready checklist (must pass)

obs-migrate doctor must show:

• Ready.
• Required dependencies ok
• For Datadog API work: datadog (datadog-api-client): ok
• uv/uvx on PATH is reported for information only — no command needs it at runtime

Then run one offline smoke (still no source credentials needed):

uvx --from 'elastic-observability-migration[all]' obs-migrate list-samples

Exit 0 + sample JSON ⇒ install verified. Hand off to the skill the user originally asked for.

Kibana tooling note

No external Kibana tool is needed. obs-migrate migrate writes native Dashboard-as-Code artifacts (dashboards/native/*.native.json) and obs-migrate upload --artifact-dir <dir> sends them through the typed Kibana Dashboards API (PUT /api/dashboards/{id}) — there is no dashboard-YAML compile step, so nothing installs or fetches kb-dashboard-cli / kb-dashboard-lint, and doctor does not check for them. Migrate and upload work without the [kibana] extra.

Honest limits / Do NOT

• Do NOT send users to Docker or Windows install paths (unsupported).
• Do NOT document @main git installs — pin a release tag.
• Do NOT fold Grafana/Datadog/Elastic credential setup into this skill — hand off to connect-to-o11y-source.
• Do NOT duplicate long install blocks in other skills — point here.
• Do NOT claim install success without a Ready doctor (or explain the exact doctor failure and fix it).

See also

• connect-to-o11y-source — credentials and live source proof after install.
• evaluate-o11y-permissions — Elastic/Kibana key capabilities.
• https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md — Install And Setup (canonical).
• README.md — short operator install.
• PyPI: https://pypi.org/project/elastic-observability-migration/