Documentación / Uso / Comandos

Comandos

Ocho comandos: diagnose, init, login, logout, doctor, migrate, pr y mcp. Además de --version.

--version

kedgeway --version
kedgeway -V

Muestra la versión instalada, leída de package.json, y sale con 0.

diagnose

kedgeway diagnose [path-or-url] [--ref <ref>] [--json] [--format <text|json|sarif|annotations>] [--sarif <file>] [--annotations <file>] [--fixture <file>] [--fail-on <severity>] [--offline] [--no-cache] [--max-age <duration>]

Escanea el repo en path-or-url (por defecto, el directorio actual), obtiene los datos del ecosistema e imprime un reporte. Usa Raven, salvo que pases --fixture. La fuente es una ruta local, una URL de git (https://, ssh:// o git@host:owner/repo) o la forma corta de GitHub owner/repo. Un directorio local existente tiene prioridad sobre la forma corta. Una fuente remota se clona de forma superficial en un directorio temporal y se borra al terminar. Consulta Repositorios remotos.

--ref <ref>

Rama o tag que se escanea cuando la fuente es un repositorio remoto. Puede repetir el /tree/<ref> de la URL, pero no contradecirlo. Con una ruta local es un error y sale con 1. También en migrate.

--json

Muestra el diagnóstico como JSON en lugar de texto. El objeto tiene findings (cada uno con severity, code, message, file, evidence) y summary (critical, warning, info).

--format <text|json|sarif|annotations>

Elige el formato de stdout. --json equivale a --format json; usar ambos sale con 1. annotations imprime un comando de workflow de GitHub por hallazgo (::error, ::warning, ::notice, con el archivo de manifiesto y la línea) y luego el reporte de texto normal.

--sarif <file>

También escribe un log SARIF 2.1.0 en file. Stdout sigue respetando --format.

--annotations <file>

También escribe las anotaciones de GitHub en file. Stdout sigue respetando --format. La línea sale de un escaneo aproximado del manifiesto. Consulta GitHub Action.

--offline

Usa solo el snapshot del ecosistema en caché y nunca llama a Raven. Sale con 1 si no hay caché; contradice --no-cache; se ignora con una advertencia cuando hay --fixture. También en migrate. En doctor, el mismo flag solo omite la verificación de conexión con Raven.

--no-cache

Ignora el snapshot en caché y obtiene los datos en vivo. El resultado se guarda igual en la caché. También en migrate.

--max-age <duration>

Antigüedad máxima de un snapshot en caché antes de volver a obtenerlo: 30s, 15m, 24h, 2d. Por defecto, 24h. También en migrate. Consulta Fuentes de datos.

--fixture <file>

Lee el snapshot del ecosistema desde un archivo JSON en lugar de llamar a Raven. No requiere iniciar sesión. Consulta Fixtures.

--fail-on <severity>

Termina con código 2 si algún hallazgo está en critical, warning o info, o por encima. Cualquier otro valor es un error y sale con 1.

kedgeway diagnose ./my-contract --fail-on critical
kedgeway diagnose . --json > report.json
kedgeway diagnose https://github.com/o/r
kedgeway diagnose o/r --ref v1.2.0 --fail-on warning

init

kedgeway init [path] [--force] [--print] [--mode <diagnose|pr>]

Escribe .github/workflows/kedgeway.yml dentro de path (por defecto, el directorio actual). El workflow se ejecuta con cada push a main o master y en los pull requests, y usa Klorenn/kedgeway@v<installed version> con path: ., fail-on: warning y auth: ${{ secrets.KEDGEWAY_AUTH }}. Después, crea el secreto de repositorio KEDGEWAY_AUTH con la salida de kedgeway login --export. Consulta GitHub Action.

--force

Sobrescribe un archivo de workflow existente. Sin ella, el archivo existente queda igual y el comando sale con 1.

--print

Muestra el YAML del workflow en stdout y no escribe nada.

--mode <diagnose|pr>

Qué workflow escribir. diagnose (el valor por defecto) escribe kedgeway.yml como se describe arriba. pr escribe en su lugar .github/workflows/kedgeway-pr.yml: un job semanal (los lunes a las 09:00 UTC, además de workflow_dispatch) con contents: write y pull-requests: write, actions/checkout con fetch-depth: 0 y la action con mode: pr. Después te recuerda permitir que GitHub Actions cree pull requests. Consulta Abrir un PR de migración.

Sale con 0 si todo sale bien. Sale con 1 si el archivo existe y no se usó --force, o si falla la escritura.

login

kedgeway login

Inicia una autorización OAuth nueva con Stellar Raven y guarda el token. Imprime Logged in to Stellar Raven. si funciona. Consulta Autenticación.

kedgeway login --no-browser

login --no-browser es para máquinas sin navegador. Muestra la URL de autorización en lugar de abrirla. Abre la URL en cualquier lugar, inicia sesión y pega la URL de redirección (o solo su code) en la terminal. Una URL pegada se compara con el state de OAuth del intento de inicio de sesión; un código suelto no lleva state. También puedes reenviar el puerto del callback con ssh -L para que la redirección llegue directamente a kedgeway. Se combina con --export. Consulta Inicio de sesión sin navegador.

kedgeway login --export

login --export imprime tus credenciales guardadas como un secreto en base64 para CI y no borra nada. Solo inicia sesión antes si no hay nada guardado, y abre un navegador salvo que también pases --no-browser. Stdout es el secreto; stderr advierte que lo es. Si KEDGEWAY_AUTH ya está definida en el entorno, ese valor se ignora y se exporta el inicio de sesión guardado. Pon la salida en un secreto KEDGEWAY_AUTH. Consulta CI.

logout

kedgeway logout

Borra las credenciales guardadas. Imprime si se borró algo y sale con 0 en ambos casos.

doctor

kedgeway doctor [--offline]

Una autoverificación que no cambia nada. Imprime una línea por verificación, ok, warn, fail o skip:

• Versión de Node (22.12 o más reciente).
• Autenticación: una KEDGEWAY_AUTH válida en el entorno, un auth.json con tokens, o ninguna.
• Caché de snapshots: ruta y antigüedad.
• Stellar CLI: ejecuta stellar --version sin shell (límite de 5 segundos). Si no está instalada da warn, porque es opcional (guía de instalación). Con un snapshot en caché, el major actual o uno más nuevo da ok, un major de atraso da warn y dos o más dan fail. Con --offline o sin snapshot da ok y solo reporta la versión instalada.
• Conexión con Raven: una llamada search liviana con un límite de 10 segundos. --offline la omite. Usa una copia de solo lectura de tus credenciales, así que renovar el token no puede modificar auth.json.

Sale con 0 cuando nada falló (las advertencias no lo hacen fallar) y con 1 cuando falló alguna verificación.

migrate

kedgeway migrate [path-or-url] [--ref <ref>] [--dry-run] [--write] [--fixture <file>] [--offline] [--no-cache] [--max-age <duration>]

Imprime una guía de migración y un diff unificado de los cambios de versión del SDK. Por defecto es un dry run, y --dry-run es ese mismo modo de forma explícita. --write aplica los cambios al manifiesto. Pasar --dry-run y --write a la vez sale con 1. --offline, --no-cache y --max-age funcionan igual que en diagnose. Sale con 0 si no hay nada que hacer, si el dry run solo tiene pasos manuales o si se aplicaron los cambios; con 2 si un dry run tiene al menos un cambio automático o si una escritura omitió algún paso; con 1 ante un error, incluida una escritura rechazada. Solo edita manifiestos y avisa de cualquier lockfile que quede desactualizado, con un paso manual para regenerarlo. Consulta la guía de migración.

path-or-url acepta las mismas fuentes que diagnose. Migrar una fuente remota solo admite dry run: --write sale con 2 e imprime remote sources are dry-run only; clone it and run migrate locally.

kedgeway migrate https://gitlab.com/group/sub/r

pr

kedgeway pr [path] [--dry-run] [--base <branch>] [--branch <name>] [--repo <owner/repo>] [--token <token>] [--refresh-lockfiles] [--label <name>] [--draft] [--json]

Convierte el plan de migrate en un pull request. Ejecútalo dentro de un checkout local del repositorio; usa tu sesión de Raven y tu GITHUB_TOKEN, y no hay ningún servicio alojado. Una ejecución hace tres cosas:

1. Planifica la migración sobre un árbol de trabajo limpio. Un árbol con cambios termina con código 2, salvo con --dry-run. Si no hay ningún cambio automático, imprime el motivo y termina con código 0 sin tocar git ni la red.
2. Crea, o reinicia, la rama kedgeway/migrate-<major> (kedgeway/migrate-toolchain cuando no hay un major de destino concreto) a partir de origin/<base> (nunca desde el HEAD local, así que los commits locales sin publicar nunca llegan al PR), aplica los mismos cambios que migrate --write, opcionalmente regenera los lockfiles y hace el commit solo de los archivos que editó más los lockfiles que regeneró (nunca git add -A) como kedgeway[bot] <kedgeway@users.noreply.github.com>. Define KEDGEWAY_GIT_AUTHOR_NAME y KEDGEWAY_GIT_AUTHOR_EMAIL para cambiar el autor. Los hooks y la firma están desactivados para ese commit.
3. Hace force-push de esa rama con --force-with-lease, de modo que los commits que una persona haya agregado a la rama del PR no se sobrescriben en silencio; luego crea el pull request o actualiza el que ya está abierto para ella, aplica la etiqueta e imprime la URL del PR. La rama es propia de kedgeway, así que usa un nombre en el que nada más escriba.

Nunca hay más de un PR abierto por rama. El nombre de la rama sale del plan, así que la misma migración siempre llega a la misma rama. Si un PR abierto ya tiene esa rama como head, kedgeway actualiza su título y su descripción, y el force-push renueva sus commits; si no, abre uno nuevo. Un PR cerrado o fusionado no impide una nueva ejecución. Cuando cambia el major de destino, también cambia el nombre de la rama, así que se abre un PR nuevo y el anterior queda abierto para que lo cierres tú.

El pull request contiene:

• Un título como chore(deps): migrate soroban-sdk to 28 (72 caracteres como máximo), o chore(toolchain): kedgeway migration.
• Una línea de resumen con la versión de origen y la de destino.
• Una tabla de hallazgos con código, severidad y file:line.
• Los cambios.
• Los pasos manuales, como una lista de tareas.
• La guía de migración.
• Una nota sobre lockfiles cuando uno de ellos fija una dependencia que cambió y todavía hay que regenerarlo.
• Notas sobre lo que no se pudo aplicar o regenerar.
• La procedencia (fuente del snapshot y observedAt) y el pie Opened by kedgeway <version>.

--dry-run

Muestra el título y la descripción. No escribe nada en git ni usa la red. Funciona con un árbol con cambios y no necesita token.

--base <branch>

Rama a la que apunta el PR. Por defecto, la rama predeterminada del repositorio según la API; si no está disponible, usa la rama actual con una advertencia.

--branch <name>

Rama head que se publica. Por defecto, kedgeway/migrate-<major>. Debe empezar con kedgeway/; cualquier otra termina con código 2 antes de publicar nada. Nunca puede ser igual a la rama base, a la rama por defecto del repositorio ni a la rama actual. Solo letras, dígitos y ._/-.

--allow-any-branch

Levanta solo la regla del prefijo kedgeway/ de --branch, para un nombre en el que solo escribe kedgeway, porque la rama recibe un force-push. La rama sigue sin poder ser igual a la base, a la rama por defecto ni a la rama actual. Solo CLI: la herramienta pr de MCP y la entrada pr-branch de la action no lo tienen.

--repo <owner/repo>

Repositorio de GitHub. Por defecto, GITHUB_REPOSITORY; si no, se obtiene de git remote get-url origin.

--token <token>

Token de GitHub. Por defecto, GITHUB_TOKEN. Es mejor usar la variable de entorno: otros usuarios pueden ver argv.

--refresh-lockfiles

Regenera solo los lockfiles que tocó el plan, y solo si la herramienta está instalada: cargo update -p soroban-sdk, npm install --package-lock-only, pnpm install --lockfile-only, yarn install --mode update-lockfile (npm y pnpm reciben además --ignore-scripts). Desactivado por defecto. Una falla se convierte en una nota en la descripción del PR, no en un error fatal.

--label <name>

Etiqueta que se aplica. Por defecto, kedgeway, y se crea si no existe. Una falla con la etiqueta es una advertencia, no un error.

--draft

Abre el PR como borrador.

--json

Imprime { action, url?, branch, title }. action es create, update, skip o dry-run; skip agrega reason y dry-run agrega body.

--fixture, --offline, --no-cache, --max-age

Igual que en diagnose y migrate.

kedgeway pr --dry-run
kedgeway pr --draft --refresh-lockfiles

Termina con código 0 si el PR se creó o se actualizó, o si la ejecución se omitió. Termina con código 1 ante una falla de git o de la API. Termina con código 2 ante un error de uso: un árbol con cambios, la falta de token o de repositorio, un --branch o un --repo no válidos, una fuente remota por URL o flags de caché contradictorios.

Solo cambian las cadenas de versión de los manifiestos, más los lockfiles que elijas regenerar. El código fuente nunca se reescribe, así que el CI del PR es tu red de seguridad. Solo rutas locales. Para ejecutarlo de forma programada, usa kedgeway init --mode pr; consulta GitHub Action.

mcp

kedgeway mcp [--allow-write]

Ejecuta un servidor MCP por stdio. Nunca inicia OAuth: primero inicia sesión. --allow-write permite que la herramienta migrate edite archivos y que la herramienta pr abra pull requests; sin ella, write: true devuelve un error y los dry runs siguen funcionando. Consulta Servidor MCP.

Códigos de salida

logout sale con 0 se haya borrado o no un archivo de credenciales. --help sale con 0. Un comando o un flag desconocidos salen con 1.