Creating cards on the Canvas

There are two ways to create a card: the bar at the top of the board and right-clicking the background. Both create the same kind of card; right-clicking has the advantage of placing the card at the point you indicated.

From the top bar

The bar offers Conversation, Terminal, Note (with the Note and Note group submenu), Browser and Phone.

• Conversation opens an assistant picker before creating the card: choosing the assistant is part of creating it, not a step afterwards.
• Terminal offers a plain shell or a terminal already running an assistant.
• Note creates an empty note card; Note group creates the binder. Both are detailed in Notes on the Canvas.
• Phone is disabled when the emulator is not available in the build, with the notice “The emulator is not available in this version yet”.

By right-clicking the background

Right-clicking the board background, the “Add here” item creates the card where you indicated. For Conversation and Terminal it opens a submenu to choose the assistant.

The File card is in neither that list nor the bar: it is born when you open a real project file, and it reuses the same opening queue as the Files screen.

Who can create agent cards

Only the orchestrator card creates Conversation and Terminal cards. A card without that role that asks for an agent is refused, and the request must be handed to the orchestrator.

The exception exists so the board never gets stuck: the first agent card of an empty Canvas is born orchestrator. A fresh Canvas therefore always has a way to start. Note, file, browser and phone cards are not agents and anyone can create them.

From the command line

An agent can create cards without touching the interface:

elyra canvas create <type> [--workspace <selector>] [--agent <id>] [--role <name>]
                          [--model <id>] [--title <text>] [--content <text>]
                          [--content-file <path|->] [--position <x,y>] [--size <w,h>]
                          [--link-to <nodeId>] [--orchestrator] [--path <path>]
                          [--cwd <folder>] [--url <url>] [--device-id <id>]
                          [--platform <android|ios>] [--json]

The type is one of chat, terminal, note, file, browser, device. The flags are specific per type, and passing the wrong flag to the wrong type is refused:

Type	Own flags	Notes
chat	--agent, --model	The model is chosen here and only here.
terminal	--agent, --cwd	--model is not accepted: the assistant runs its own interface and there is no uniform way to pick the model at launch.
note	--content, --content-file, --title	Writes the .md file at birth.
file	--path (required)	The path is relative to the workspace root and the file must exist.
browser	--url	Sets the card’s initial page.
device	--device-id, --platform	Accepts android or ios.

Rules that avoid surprises:

• --position and --size take two numbers separated by a comma: "400,120" and "900,600".
• --link-to links the new card to an existing card (by id or exact title). Without the flag, the card is already linked to whoever called, when a calling card exists.
• --orchestrator is sugar for --role orquestrador; passing both is an error.
• Creating a phone card does not start the emulator: the card is only the place where it will appear.

What the command returns

Each type returns its own identifier, which is what the following commands use:

• terminal returns the session, and it starts appearing in the terminal list;
• chat returns a stable handle (in the chat_<12 hex> format), which does not appear in the terminal list — see The conversation on the Canvas;
• note returns the real absolute path of the .md file, which lives outside the project folder;
• the others return the card identifier.

Role declared at creation

The --role flag declares the intended role, but the named role is not applied at creation time yet: until that link closes, the card is born roleless and you promote it later with elyra canvas set-orchestrator <card> or with the roles dialog. The exception is the automatic one: the first agent card of an empty Canvas is born orchestrator.

After creating: what to expect

• A terminal is not ready immediately. It takes a few seconds (the known measurement is on the order of 7 seconds on Windows) to appear in the terminal list and accept input. Until then it shows up nowhere — do not recreate the card.
• A conversation session does not appear in the terminal list. It runs through the SDK, with an address of its own.
• A terminal’s folder must exist. If the directory given in --cwd does not exist when the terminal starts, it opens in the workspace folder and says so in its first lines; the root of a disk is refused before the card is created. Create the directory first.

Recovery and cleanup

• Note created without a file. If the note’s file cannot be created, the card appears on the Canvas and the notice says where Elyra tried to save it and why. Text you write there may not be saved — check the reported path before trusting the note.
• Card created by mistake. Close it with the card’s close button. Careful: closing a terminal ends the session and closing a note deletes the file.
• Terminal that does not appear. Wait out the startup time before anything else; recreating the card leaves two terminals and two processes where you wanted one.