De cero al primer proyecto

Este tutorial te lleva de “ningún proyecto” a “una tarjeta en el Canvas respondiendo” dentro de una carpeta desechable que creas para este fin. Al terminar, la limpieza elimina solo el archivo creado aquí y se niega a borrar la carpeta si contiene algo más.

Requisitos previos

• Elyra ADE instalado y activado en esta máquina. Sin una licencia válida la app no abre el área de trabajo — este tutorial empieza después de eso.
• Una terminal Bash para crear y eliminar la carpeta de muestra (en Windows, usa Git Bash). Los comandos siguientes no son comandos PowerShell.
• Opcional: una CLI de asistente instalada (por ejemplo Claude Code), si quieres ver a un agente responder. Sin ninguna instalada, el paso 5 tiene un camino alternativo con una terminal simple.

Proyecto ≠ workspace

Dos palabras que el resto del tutorial usa todo el tiempo:

• Un proyecto es el repositorio o la carpeta que agregas. Aparece en la lista Proyectos, en la barra lateral.
• Un workspace es un nombre y una carpeta dentro del proyecto. El proyecto que vas a agregar recibe un workspace predeterminado que apunta a la propia carpeta, y es sobre esa carpeta que se abren las pantallas.

Una consecuencia práctica que evita un susto: un workspace no es un worktree de git. elyra workspace list lista workspaces de Elyra; los worktrees de git pertenecen a git y viven en la pantalla Git.

Paso 1 — Crea la carpeta desechable

mkdir ~/elyra-demo && printf 'elyra demo\n' > ~/elyra-demo/readme.txt && ls ~/elyra-demo

Debes ver readme.txt. Si mkdir indica que la carpeta ya existe, detente: no se escribió ningún archivo. No uses una carpeta que contenga trabajo real para seguir esta guía.

Paso 2 — Agrega la carpeta como proyecto

En la barra lateral, haz clic en Añadir proyecto. Se abre el diálogo Añadir un proyecto, con tres puertas:

Puerta	Sirve para
Seleccionar carpeta existente	una carpeta que ya existe en esta máquina (el camino de este tutorial)
Clonar de un repositorio	clonar una URL en una carpeta nueva
Nuevo proyecto	crear una carpeta nueva y vacía

Elige Seleccionar carpeta existente, apunta a ~/elyra-demo — el campo es Carpeta del proyecto y el botón de elegir es Elegir carpeta — y confirma con el botón Añadir.

Lo que ocurre después: el proyecto entra en la lista Proyectos y Elyra activa el checkout predeterminado del proyecto (la carpeta que elegiste) y revela la pantalla de ese workspace. Si la app no consigue abrirlo, aparece el aviso Proyecto añadido, pero no abierto con la instrucción de abrirlo desde la lista de proyectos — el proyecto entró, solo que no se reveló.

Por la CLI, el mismo efecto:

elyra repo add --path ~/elyra-demo --json
elyra project list --json

repo add exige --path y resuelve rutas relativas desde el directorio actual.

Si la carpeta tiene repositorios dentro: Elyra avisa Esta carpeta tiene repositorios dentro y ofrece Abrir la carpeta igual o Importar como grupo. Para este tutorial, elige Abrir la carpeta igual — la muestra no tiene ningún repositorio dentro.

Paso 3 — Revisa el workspace

Abre la lista Proyectos y localiza elyra-demo. Bajo el proyecto aparece el workspace predeterminado, con el nombre de la carpeta. Compruébalo por la CLI:

elyra workspace list --json
elyra workspace current --json

workspace list devuelve los workspaces de Elyra, y workspace current resuelve el workspace de la carpeta donde llamaste al comando. Ninguno de los dos lista worktrees de git.

Si llamas a workspace list desde fuera de un proyecto de Elyra, lista todos los workspaces registrados; dentro de un workspace, workspace current dice en cuál estás. La referencia completa — flags, salida y errores — está en Referencia: elyra workspace list.

Paso 4 — Crea la primera tarjeta en el Canvas

Abre la pantalla Canvas del proyecto. Se abre vacía, con la invitación en el medio:

Todavía no hay nada en el tablero — Usa la barra de arriba para abrir una conversación, un terminal o una nota. El clic derecho en el fondo crea la tarjeta donde apuntes.

En la barra de creación, arriba, elige Conversación (o Terminal, si prefieres empezar por un shell puro):

• Conversación crea una tarjeta de conversación con un asistente. Si hay más de una CLI de asistente detectada en el host del workspace, el botón abre un menú para elegir; con una sola, la crea directamente.
• Terminal crea una tarjeta de terminal, con shell puro o ya con un asistente.
• Los demás botones visibles crean Nota (con la variante Grupo de notas) y Navegador. La tarjeta de Archivo no sale de la barra: aparece cuando abres un archivo real.

Haz clic con el botón derecho en el fondo del Canvas para crear una tarjeta en el punto exacto en que apuntaste.

Detalle de comportamiento: la primera tarjeta de agente de un Canvas vacío nace orquestadora, por rol. Eso es lo que autoriza a esa tarjeta a hablar con las demás después.

Sin ningún asistente instalado: el botón Conversación no crea nada — muestra el aviso Instala un asistente (como Claude Code) para empezar a conversar. En ese caso, usa Terminal con shell puro y sigue el paso 5 por el camino alternativo.

Paso 5 — Pide algo que no exija decisión

Con la tarjeta creada, escribe en su campo de entrada una petición simple y de solo lectura:

lista los archivos de esta carpeta y dime qué encontraste

La tarjeta se ejecuta en la carpeta del workspace — ese es el vínculo entre la conversación y tu proyecto. Como la carpeta es desechable, puedes pedir un cambio después (por ejemplo, crear un segundo archivo) sin ningún riesgo.

Camino alternativo, sin asistente: en la tarjeta de Terminal, ejecuta el mismo tipo de comprobación en el shell:

pwd
ls -la

El pwd debe apuntar a la carpeta del workspace del proyecto — la misma que agregaste.

Paso 6 — Lo que observas

Al final del recorrido, sin depender de ningún agente específico:

1. El proyecto elyra-demo está en la lista Proyectos, con el workspace predeterminado apuntando a la carpeta elegida.
2. La pantalla Canvas de ese workspace tiene la tarjeta que creaste, con su sesión.
3. Cambiar de pantalla no termina la sesión de la tarjeta: las sesiones viven en el proceso principal de la app, y volver al Canvas encuentra la tarjeta como estaba.
4. Cerrar y reabrir la app no pierde la disposición del Canvas ni las sesiones — el estado se restaura.

La separación completa entre las cuatro pantallas todavía no está terminada: una pantalla puede mostrar contenido de otra. No cuentes con el aislamiento total entre ellas.

Si algo sale mal

Síntoma	Causa probable	Qué hacer
La carpeta elegida ya tiene archivos y Elyra la rechaza	el camino Nuevo proyecto exige una carpeta vacía	usa Seleccionar carpeta existente, que es el camino de este tutorial
Proyecto añadido, pero no abierto	la apertura del checkout predeterminado perdió el turno (por ejemplo, navegaste en medio)	abre el proyecto desde la lista Proyectos
El botón Conversación muestra “Instala un asistente…”	ninguna CLI de asistente detectada en este host	instala la CLI y vuelve a esta pantalla, o usa Terminal con shell puro
La tarjeta de Terminal no acepta texto en el primer instante	la terminal tarda unos segundos en estar lista	espera unos segundos; no crees otra tarjeta
elyra workspace list devuelve repo_not_found	el selector --repo no coincidió con ningún repositorio registrado	compruébalo con elyra repo list --json y repite con un selector exacto

Limpieza — elimina solo el archivo creado en este tutorial

En este orden:

1. Cierra la tarjeta. En el encabezado de la tarjeta, usa el botón de cerrar (o el menú de la tarjeta → Cerrar). Eso termina la sesión de la tarjeta — y es lo que quieres aquí, porque la muestra no tiene nada que guardar. Para mantener una sesión viva, el cierre desde la tarjeta tiene la variante que preserva la sesión; no es el caso ahora.

2. Borra el proyecto de Elyra. En la lista Proyectos, abre el menú de contexto del proyecto y elige Borrar proyecto. El diálogo pide que escribas el nombre del proyecto para armar el botón — escribe elyra-demo y confirma. Nada sale del disco: la carpeta sigue exactamente donde estaba, el proyecto solo deja de ser conocido por Elyra. No hay comando de CLI para quitar un proyecto.

3. Elimina solo la muestra. Comprueba que ~/elyra-demo es la carpeta que acabas de crear e inspecciona su contenido antes de borrar:

ls -la ~/elyra-demo
rm ~/elyra-demo/readme.txt && rmdir ~/elyra-demo

rmdir elimina la carpeta solo si está vacía. Si el agente creó otro archivo o la carpeta contiene cualquier otro dato, la eliminación falla sin borrar ese contenido. Inspecciona cada archivo restante y decide qué hacer; nunca uses rm -rf para terminar este tutorial.

Si también creaste workspaces extra durante la exploración, quítalos desde la pantalla Git o desde la lista de workspaces, uno por uno, comprobando antes qué hay dentro.