---
id: "canvas.criar-cartoes"
titulo: "Creating cards on the Canvas"
resumo: "Open a conversation, terminal, note, note group, browser or phone on the board — from the bar, from right-click, and from the command line."
idioma: "en"
tipo: "guia"
categoria: "telas"
aplicavelDesde: "0.0.16"
capabilities: ["canvas.cards.create", "canvas.cards.birth-role"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/en/canvas/criar-cartoes/"
fonte: "pt-br/canvas/criar-cartoes.md"
caminhoPublico: "docs/publica/en/canvas/criar-cartoes.md"
hashFonte: "sha256:f9314fdc6512ee7f76ff4f009575a9f69f257b52b89047c56614940505c294bd"
hashDestaPagina: "sha256:aa1cadc9164d744d1a317cd798f7eff1834bfcc718d971bbdc578809b9f6a24a"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/canvas/criar-cartoes.md fonteHash=sha256:f9314fdc6512ee7f76ff4f009575a9f69f257b52b89047c56614940505c294bd estado=atual -->

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](/docs/en/canvas/notas/visao-geral/).
- **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](/docs/en/canvas/cartao-conversa/);
- `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.