From scratch to your first project

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

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:

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:

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.

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:

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:

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.