---
id: "primeiro-projeto"
titulo: "From scratch to your first project"
resumo: "Add a disposable folder as a project, open the first Canvas card, and delete everything at the end — without touching any real work."
idioma: "en"
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/en/first-project/"
fonte: "pt-br/primeiro-projeto.md"
caminhoPublico: "docs/publica/en/first-project.md"
hashFonte: "sha256:51e9aa47ca396c9039af222f520752866755dc14f4199e963aab2cce308bf11b"
hashDestaPagina: "sha256:03d5a0a2c5a21a5d5c85a8a980fb9dd96424ffcc4a1f7b04d8b91426a7d410d9"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/primeiro-projeto.md fonteHash=sha256:51e9aa47ca396c9039af222f520752866755dc14f4199e963aab2cce308bf11b estado=atual -->

This tutorial takes you from "no project" to "a card on the Canvas answering" inside a **disposable folder** you create for this purpose. At the end, cleanup removes only the file created here and refuses to delete a folder containing anything else.

**Prerequisites**

- Elyra ADE installed and **activated** on this machine. Without a valid license the app does not open the workspace — this tutorial starts after that.
- A Bash terminal to create and remove the sample folder (on Windows, use Git Bash). The commands below are not PowerShell commands.
- Optional: an assistant CLI installed (for example Claude Code), if you want to see an agent answer. With none installed, step 5 has an alternative path using a plain terminal.

## Project ≠ workspace

Two words the rest of the tutorial uses all the time:

- A **project** is the repository or folder you add. It appears in the **Projects** list, in the sidebar.
- A **workspace** is **a name and a folder inside the project**. The project you are about to add gets a default workspace pointing at the folder itself, and it is over that folder that the screens open.

One practical consequence that prevents a scare: **a workspace is not a git worktree**. `elyra workspace list` lists Elyra workspaces; git worktrees belong to git and live on the Git screen.

## Step 1 — Create the disposable folder

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

You should see `readme.txt`. If `mkdir` says the folder already exists, **stop**: no file was written. Do not use a folder containing real work for this walkthrough.

## Step 2 — Add the folder as a project

In the sidebar, click **Add project**. The **Add a project** dialog opens, with three doors:

| Door | Use it for |
|---|---|
| **Select an existing folder** | a folder that already exists on this machine (this tutorial's path) |
| **Clone from a repository** | cloning a URL into a new folder |
| **New project** | creating a new, empty folder |

Choose **Select an existing folder**, point it at `~/elyra-demo` — the field is **Project folder** and the browse button is **Choose folder** — and confirm with the **Add** button.

**What happens next:** the project joins the **Projects** list, and Elyra activates the project's *default checkout* (the folder you chose) and reveals that workspace's screen. If the app cannot open it, the notice **Project added, but not opened** appears, telling you to open it from the projects list — the project is in, it just was not revealed.

**The same effect through the CLI:**

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

`repo add` requires `--path` and resolves relative paths from the current directory.

**If the folder has repositories inside:** Elyra warns **This folder has repositories inside** and offers **Open the folder anyway** or **Import as a group**. For this tutorial, choose **Open the folder anyway** — the sample has no repository inside it.

## Step 3 — Check the workspace

Open the **Projects** list and find `elyra-demo`. Under the project you will see the default workspace, named after the folder. Check it through the CLI:

```bash
elyra workspace list --json
elyra workspace current --json
```

`workspace list` returns the Elyra workspaces, and `workspace current` resolves the workspace of the folder you called the command from. Neither one lists git worktrees.

If you call `workspace list` from outside an Elyra project, it lists every registered workspace; inside a workspace, `workspace current` tells you which one you are in. The full reference — flags, output and errors — is in [Reference: `elyra workspace list`](/docs/en/cli-workspace-list/).

## Step 4 — Create the first card on the Canvas

Open the project's **Canvas** screen. It opens **empty**, with the invitation in the middle:

> **Nothing on the board yet** — Use the bar at the top to open a conversation, a terminal, or a note. Right-click the background to create a card where you point.

On the creation bar at the top, choose **Conversation** (or **Terminal**, if you would rather start with a plain shell):

- **Conversation** creates a conversation card with an assistant. If more than one assistant CLI is detected on the workspace host, the button opens a menu to pick one; with only one, it creates it directly.
- **Terminal** creates a terminal card, with a plain shell or already with an assistant.
- The other visible buttons create **Note** (with the Note group variant) and **Browser**. A **File** card does not come from the bar: it appears when you open a real file.

Right-click the Canvas background to create a card **at the exact point** you aimed at.

> Behaviour detail: the first agent card of an empty Canvas is born as the **orchestrator**, through its role. That is what authorizes this card to talk to the others later.

**With no assistant installed:** the **Conversation** button creates nothing — it shows the notice **Install an assistant (such as Claude Code) to start chatting.** In that case, use **Terminal** with a plain shell and follow step 5 through the alternative path.

## Step 5 — Ask for something that requires no decision

With the card created, type a simple, read-only request in its input field:

```
list the files in this folder and tell me what you found
```

The card runs **in the workspace folder** — that is the link between the conversation and your project. Because the folder is disposable, you can ask for a change later (creating a second file, for example) with no risk at all.

**Alternative path, without an assistant:** in the **Terminal** card, run the same kind of check in the shell:

```bash
pwd
ls -la
```

`pwd` should point at the project workspace folder — the one you added.

## Step 6 — What you observe

At the end of the walkthrough, without depending on any specific agent:

1. The `elyra-demo` project is in the **Projects** list, with the default workspace pointing at the folder you chose.
2. That workspace's **Canvas** screen has the card you created, with its session.
3. Switching screens does **not** end the card's session: sessions live in the app's main process, and going back to the Canvas finds the card as it was.
4. Closing and reopening the app loses neither the Canvas arrangement nor the sessions — the state is restored.

> The full separation between the four screens **is not complete yet**: one screen can show another's content. Do not count on full isolation between them.

## If something goes wrong

| Symptom | Likely cause | What to do |
|---|---|---|
| The chosen folder already has files and Elyra refuses | the **New project** path requires an empty folder | use **Select an existing folder**, which is this tutorial's path |
| **Project added, but not opened** | opening the default checkout lost its turn (you navigated in the middle, for example) | open the project from the **Projects** list |
| The **Conversation** button shows "Install an assistant…" | no assistant CLI detected on this host | install the CLI and come back to this screen, or use **Terminal** with a plain shell |
| The Terminal card does not accept text at first | the terminal takes a few seconds to become ready | wait a few seconds; do **not** create another card |
| `elyra workspace list` returns `repo_not_found` | the `--repo` selector matched no registered repository | check with `elyra repo list --json` and retry with an exact selector |

## Cleanup — removes only the file created by this tutorial

In this order:

**1. Close the card.** In the card header, use the close button (or the card menu → **Close**). That ends the card's session — and that is what you want here, because the sample has nothing to save. To keep a session alive, closing through the card has the variant that preserves the session; that is not the case now.

**2. Delete the project from Elyra.** In the **Projects** list, open the project's context menu and choose **Delete project**. The dialog asks you to type the project name to arm the button — type `elyra-demo` and confirm. **Nothing leaves the disk:** the folder stays exactly where it was, the project is just no longer known to Elyra. There is no CLI command to remove a project.

**3. Remove only the sample.** Check that `~/elyra-demo` is the folder you just created and inspect its contents before deleting:

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

`rmdir` removes the folder only if it is empty. If the agent created another file or the folder contains any other data, removal **fails without deleting that content**. Inspect each remaining file and decide what to do; never use `rm -rf` to finish this tutorial.

If you also created extra workspaces while exploring, remove them from the Git screen or the workspace list, one by one, checking what is inside first.