---
id: "primeiro-projeto"
titulo: "Do zero ao primeiro projeto"
resumo: "Adicionar uma pasta descartável como projeto, abrir o primeiro cartão no Canvas e apagar tudo no fim — sem tocar em nenhum trabalho de verdade."
idioma: "pt-br"
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/pt-br/primeiro-projeto/"
fonte: "pt-br/primeiro-projeto.md"
caminhoPublico: "docs/publica/pt-br/primeiro-projeto.md"
hashFonte: "sha256:51e9aa47ca396c9039af222f520752866755dc14f4199e963aab2cce308bf11b"
hashDestaPagina: "sha256:51e9aa47ca396c9039af222f520752866755dc14f4199e963aab2cce308bf11b"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
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

```bash
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:**

```bash
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:

```bash
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`](/docs/pt-br/cli-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:

```bash
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:

```bash
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.