Do zero ao primeiro projeto

Este tutorial leva você de “nenhum projeto” a “um cartão no Canvas respondendo” em uma pasta descartável, criada por você só para isso. No fim, a limpeza remove apenas o arquivo criado aqui e recusa apagar a pasta se houver outros arquivos.

Pré-requisitos

• Elyra ADE instalado e ativado nesta máquina. Sem licença válida o app não abre a área de trabalho — este tutorial começa depois disso.
• Um terminal com Bash para criar e remover a pasta de amostra (no Windows, use o Git Bash). Os comandos abaixo não são comandos PowerShell.
• Opcional: uma CLI de assistente instalada (por exemplo Claude Code), se você quiser ver um agente responder. Sem nenhuma instalada, o passo 5 tem um caminho alternativo com terminal puro.

Projeto ≠ workspace

Duas palavras que o resto do tutorial usa o tempo todo:

• Projeto é o repositório ou a pasta que você adiciona. Ele aparece na lista Projetos, na barra lateral.
• Workspace é um nome e uma pasta dentro do projeto. O projeto que você vai adicionar ganha um workspace padrão apontando para a própria pasta, e é sobre essa pasta que as telas abrem.

Uma consequência prática que evita susto: um workspace não é um worktree do git. elyra workspace list lista workspaces do Elyra; worktrees do git pertencem ao git e vivem na tela Git.

Passo 1 — Crie a pasta descartável

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

Você deve ver readme.txt. Se mkdir disser que a pasta já existe, pare: nenhum arquivo foi escrito. Não use uma pasta com trabalho real para seguir este roteiro.

Passo 2 — Adicione a pasta como projeto

Na barra lateral, clique em Adicionar projeto. Abre o diálogo Adicionar um projeto, com três portas:

Porta	Serve para
Selecionar pasta existente	uma pasta que já existe nesta máquina (o caminho deste tutorial)
Clonar de um repositório	clonar uma URL para uma pasta nova
Novo projeto	criar uma pasta nova e vazia

Escolha Selecionar pasta existente, aponte para ~/elyra-demo — o campo é Pasta do projeto e o botão de escolher é Escolher pasta — e confirme no botão Adicionar.

O que acontece em seguida: o projeto entra na lista Projetos e o Elyra ativa o checkout padrão do projeto (a pasta que você escolheu) e revela a tela desse workspace. Se o app não conseguir abrir, aparece o aviso Projeto adicionado, mas não aberto com a instrução de abrir pela lista de projetos — o projeto entrou, só não foi revelado.

Pela CLI, o mesmo efeito:

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

repo add exige --path e resolve caminhos relativos a partir do diretório atual.

Se a pasta tiver repositórios dentro: o Elyra avisa Esta pasta tem repositórios dentro e oferece Abrir a pasta assim mesmo ou Importar como grupo. Para este tutorial, escolha Abrir a pasta assim mesmo — a amostra não tem repositório nenhum dentro.

Passo 3 — Confira o workspace

Abra a lista Projetos e localize elyra-demo. Sob o projeto aparece o workspace padrão, com o nome da pasta. Confira pela CLI:

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

workspace list devolve os workspaces do Elyra, e workspace current resolve o workspace da pasta onde você chamou o comando. Nenhum dos dois lista worktrees do git.

Se você chamar workspace list de fora de um projeto do Elyra, ela lista todos os workspaces registrados; dentro de um workspace, workspace current diz em qual você está. A referência completa — flags, saída e erros — está em Referência: elyra workspace list.

Passo 4 — Crie o primeiro cartão no Canvas

Abra a tela Canvas do projeto. Ela abre vazia, com o convite no meio:

Nada no quadro ainda — Use a barra no topo para abrir uma conversa, um terminal ou uma nota. O clique direito no fundo cria o cartão onde você apontar.

Na barra de criação, no topo, escolha Conversa (ou Terminal, se preferir começar por um shell puro):

• Conversa cria um cartão de conversa com um assistente. Se houver mais de uma CLI de assistente detectada no host do workspace, o botão abre um menu para escolher; com uma só, cria direto.
• Terminal cria um cartão de terminal, com shell puro ou já com um assistente.
• Os demais botões visíveis criam Nota (com a variante Grupo de notas) e Navegador. Cartão de Arquivo não sai da barra: ele nasce quando você abre um arquivo real.

Clique com o botão direito no fundo do Canvas para criar um cartão no ponto exato em que você apontou.

Detalhe de comportamento: o primeiro cartão de agente de um Canvas vazio nasce orquestrador, por papel. É o que autoriza esse cartão a falar com os outros depois.

Sem nenhum assistente instalado: o botão Conversa não cria nada — ele mostra o aviso Instale um assistente (como o Claude Code) para começar a conversar. Nesse caso, use Terminal com shell puro e siga o passo 5 pelo caminho alternativo.

Passo 5 — Peça algo que não exija decisão

Com o cartão criado, escreva no campo de entrada dele um pedido simples e de leitura:

liste os arquivos desta pasta e diga o que encontrou

O cartão roda na pasta do workspace — é essa a ligação entre a conversa e o seu projeto. Como a pasta é descartável, você pode pedir uma alteração depois (por exemplo, criar um segundo arquivo) sem risco nenhum.

Caminho alternativo, sem assistente: no cartão de Terminal, rode o mesmo tipo de verificação no shell:

pwd
ls -la

O pwd deve apontar para a pasta do workspace do projeto — a mesma que você adicionou.

Passo 6 — O que você observa

Ao fim do roteiro, sem depender de nenhum agente específico:

1. O projeto elyra-demo está na lista Projetos, com o workspace padrão apontando para a pasta escolhida.
2. A tela Canvas desse workspace tem o cartão que você criou, com a sessão dele.
3. Trocar de tela não encerra a sessão do cartão: as sessões vivem no processo principal do app, e voltar ao Canvas encontra o cartão como estava.
4. Fechar e reabrir o app não perde o arranjo do Canvas nem as sessões — o estado é restaurado.

A separação completa entre as quatro telas ainda não está concluída: uma tela pode mostrar conteúdo de outra. Não conte com o isolamento total entre elas.

Se algo der errado

Sintoma	Causa provável	O que fazer
A pasta escolhida já tem arquivos e o Elyra recusa	o caminho Novo projeto exige pasta vazia	use Selecionar pasta existente, que é o caminho deste tutorial
Projeto adicionado, mas não aberto	a abertura do checkout padrão perdeu o turno (por exemplo, você navegou no meio)	abra o projeto pela lista Projetos
O botão Conversa mostra “Instale um assistente…”	nenhuma CLI de assistente detectada neste host	instale a CLI e volte a esta tela, ou use Terminal com shell puro
O cartão de Terminal não aceita texto no primeiro instante	o terminal leva alguns segundos para ficar pronto	espere alguns segundos; não crie outro cartão
elyra workspace list devolve repo_not_found	o seletor --repo não casou com nenhum repositório registrado	confira com elyra repo list --json e repita com um seletor exato

Limpeza — remove somente o arquivo criado neste tutorial

Nesta ordem:

1. Feche o cartão. No cabeçalho do cartão, use o botão de fechar (ou o menu do cartão → Fechar). Isso encerra a sessão do cartão — e é o que você quer aqui, porque a amostra não tem nada a salvar. Para manter uma sessão viva, o fechamento pelo cartão tem a variante que preserva a sessão; não é o caso agora.

2. Apague o projeto do Elyra. Na lista Projetos, abra o menu de contexto do projeto e escolha Apagar projeto. O diálogo pede que você digite o nome do projeto para armar o botão — digite elyra-demo e confirme. Nada sai do disco: a pasta continua exatamente onde estava, o projeto apenas deixa de ser conhecido pelo Elyra. Não há comando de CLI para remover projeto.

3. Remova somente a amostra. Confira que ~/elyra-demo é a pasta que você acabou de criar e veja seu conteúdo antes de apagar:

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

rmdir só remove a pasta se ela estiver vazia. Se o agente criou outro arquivo ou a pasta contém qualquer outro dado, a remoção falha sem apagar esse conteúdo. Examine cada arquivo restante e decida o que fazer; nunca use rm -rf para concluir este tutorial.

Se você também criou workspaces extras durante a exploração, remova-os pela tela Git ou pela lista de workspaces, um por um, conferindo antes o que há dentro.