--- id: "primeiro-projeto" titulo: "De cero al primer proyecto" resumo: "Agregar una carpeta desechable como proyecto, abrir la primera tarjeta en el Canvas y borrar todo al final — sin tocar ningún trabajo de verdad." idioma: "es" tipo: "tutorial" categoria: "comecar" aplicavelDesde: "0.0.16" capabilities: ["projects.add-existing-folder", "projects.list", "projects.remove", "workspaces.list", "canvas.cards.create", "chat.canvas.send"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/es/primer-proyecto/" fonte: "pt-br/primeiro-projeto.md" caminhoPublico: "docs/publica/es/primer-proyecto.md" hashFonte: "sha256:51e9aa47ca396c9039af222f520752866755dc14f4199e963aab2cce308bf11b" hashDestaPagina: "sha256:f0c647d7ac72cbdf6514ec491ee2027ca0fdcd38bfc8663b003976a5512060cc" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- 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 ```bash 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:** ```bash 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: ```bash 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`](/docs/es/cli-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: ```bash 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: ```bash 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.