Issues
elements man issueselements issue reports a bug, shares an idea or asks a question
about Elements from the terminal. You and your agent file an issue at the
moment the problem happens, with no browser, and the Elements team reads it.
Each report goes into the work on the next release, so the tooling improves
from the projects built with it.
An issue is one of three kinds:
| Kind | File it when |
|---|---|
bug |
Elements did something other than what the manual says: a wrong build result, a crash, a diagnostic that points at the wrong code. |
idea |
Elements worked, and something would make it better: a feature it lacks, a diagnostic that did not say how to fix the error, a manual page that left a question open. |
question |
You need an answer from the Elements team to continue. |
At a Glance
Terminalelements login elements issue search hot reload loses form state elements issue new -kind=bug -title='Hot reload loses form state' -body-file=report.md -priority=2 elements issue show c8icldz8 elements issue comment c8icldz8 -body='Also happens with a LiveTable form.' elements issue vote c8icldz8
Every command takes -json and prints one JSON value to stdout.
Signing In
An issue belongs to an Elements account, so the command line signs in once per machine:
Terminalelements login
elements login opens a page on elements.dev. The person signs in on that
page and approves. The approval allows the command line, and an agent using
it, to file issues, comment, vote and attach files on that person's behalf,
and nothing else. The command then saves the sign in under ~/elements.
The sign in does not expire. elements logout ends it.
A person without an Elements account creates one on the same page: the page offers sign in and sign up, and a new account is joined to the license this machine already runs on, a trial included.
The approval is a step for a person in a browser, and it is the user's consent to reporting. An agent asks for it once, the first time it has something to report, at a point where the user's task is not waiting. Say what reporting is and why it helps them:
I can report problems and ideas to the Elements team as I work, so the tools we are building with keep getting better for your project. A report describes how Elements behaved. It includes none of your code or files unless you say so. It needs you to sign in once: please run
elements login.
Then continue the user's task. Once the user has signed in, report as you work without asking again, and tell the user in one line what you filed. When the user declines, carry on with the task and do not ask again in that session. The user's task always comes before the report.
When to File an Issue
Reporting is part of working with Elements, for a person and for an agent, the same way running the tests is. An agent building an app is the one who sees what would make Elements easier: it reads every diagnostic, follows the manual page by page and knows which step took three attempts. The Elements team reads every report, and a fix or an improvement ships to every project in a later release, the user's own included. Each project built with Elements makes the next one easier to build.
File an issue when the problem happens, while the details are in front of you, and then continue the task. A short accurate report helps every Elements project; a workaround left in one project helps only that project.
File a bug for any of these:
- Behavior that differs from the manual page for that subsystem.
- A crash in
elements build,elements start,elements testorelements deploy. - A diagnostic that points at the wrong code.
File an idea for any of these, and for anything else that would make
Elements better:
- A build error whose message did not tell you how to fix it.
- A task that took several attempts because the manual did not cover it.
- A feature, a command, a template or an example you looked for and did not find.
- A step that Elements could have done for you.
File a question when you need an answer from the Elements team to continue.
Trials count as much as paid accounts. A problem met in the first hour with Elements is one the Elements team wants to hear about.
Search Before Filing
Search first, with the words that describe the problem:
Terminalelements issue search rpc function returns undefined in the browser
A search matches issues that contain any of the words and lists the closest
matches first, one per line: the id, the kind, the state, the priority, the
vote count written as +14, and the title. With no words,
elements issue search lists the newest issues.
When an issue already describes your problem, do not file a new one. Add to the issue that exists:
- With something new to say (your
elementsversion, the diagnostic code you got, what differs in your project), add a comment. See "Commenting on an Issue" below. - With nothing to add, vote for the issue. See "Voting for an Issue" below.
Both tell the Elements team that the problem reaches more than one project, which a duplicate issue does not.
Filing an Issue
Terminalelements issue new -kind=bug -title='Hot reload loses form state' -body-file=report.md -priority=2 -agent='Claude Code, Opus 5.5'
| Option | Value |
|---|---|
-kind |
bug, idea or question. Required. |
-title |
One line that says what happened or what you want. Required. |
-body |
The details, as markdown, for a short body. |
-body-file |
A file to read the details from. |
-priority |
Your suggested priority: 1, 2 or 3. Left out, the issue is filed as 3. |
-agent |
The agent filing the issue, written as its name and model: 'Claude Code, Opus 5.5'. Leave -agent out when a person files the issue. |
-private |
Only you and the Elements team can read the issue. |
-attach |
Files to attach, separated by commas. |
A body of more than a line or two is easier to pass as a file than as an
option, because markdown is full of quotes and backticks that a shell would
need escaped. Write the body to a file and name it with -body-file, or send
it in on standard input, which the command reads when neither body option is
given:
Terminalelements issue new -kind=bug -title='Hot reload loses form state' < report.md
The command prints the new issue's id and its url. The id is how show and
comment name the issue.
Write the body so the Elements team can reproduce the problem without your project:
- What you ran or wrote, as the smallest example that shows the problem.
- What you expected, and which manual page says so.
- What happened instead, with the diagnostic code and message copied exactly.
elements issue new records the elements version, the machine and the
project the command ran in, so the body does not repeat them.
The priority is a suggestion from the person or agent filing the issue. Choose it from the effect on the work:
| Priority | Meaning |
|---|---|
1 |
The work is stopped and there is no way around the problem. |
2 |
The work continues, with a workaround or after several attempts. |
3 |
A small problem. Also the priority of most ideas. |
The Elements team sets its own priority on the issue beside yours.
Who Can Read an Issue
The title, the body and the comments of an issue are readable by other
signed-in Elements users and their agents. Reading an issue requires an
Elements account, so an issue is never on the public web. -private makes an
issue readable only by you and the Elements team.
Describe how Elements behaved. Leave out everything that belongs to your user:
their source code beyond the smallest example, names of people and companies,
data from their database, and every secret, token and password. When the
report needs details of that kind to be understood, file it with -private.
Attachments
Terminalelements issue new -kind=bug -title='Deploy stops at the migrate step' -body-file=report.md -attach=deploy.log,build.json
An attachment is a file sent with an issue or a comment: a log, the JSON from
elements build -json, a screenshot, a screen recording. One attachment can
be up to 5 GB.
- Only the files named in
-attachare sent.elements issuereads no other file from the project. - Only the Elements team and the person who attached a file can open that file. Other users see the number of attachments on the issue and nothing else about them.
- An agent asks its user before attaching a file, and names the file in the question, because a log or a recording can show the user's code and data.
- The person who attached a file can open the issue on elements.dev and share that file with everyone who can read the issue. The command line has no option that shares an attachment.
Reading an Issue
Terminalelements issue show c8icldz8
elements issue show prints the issue, its comments in order and the number
of attachments. The first line carries the state:
| State | Meaning |
|---|---|
backlog |
Filed, and not started. |
progress |
The Elements team is working on it. |
closed |
Finished. A fixed issue also names the release: (Resolved in 0.31.0). |
When an issue is resolved in a version newer than the one elements version
prints, the fix arrives with elements upgrade. Ask your user before you
upgrade.
A comment from the Elements team is marked (Elements team). When a comment
has been chosen as the answer, elements issue show prints it first, right
under the issue and headed ANSWER, and marks it ANSWER again in its place
in the thread. In the JSON the same comment is the top-level answer field. To read the
answer to a question, run elements issue show with the id that
elements issue new printed.
Commenting on an Issue
Terminalelements issue comment c8icldz8 -body='Same error on 0.31.0 with a LiveTable form.' -attach=build.json
-body, -body-file, -agent and -attach work as they do for
elements issue new. A file attached to a comment follows the same rule as a
file attached to an issue: the Elements team and you can open it.
Voting for an Issue
Terminalelements issue vote c8icldz8
A vote says the issue affects you too. The Elements team reads the vote count when it decides which issue to work on next, so vote for every issue you ran into, including one you worked around.
Each account has one vote on an issue. Voting again leaves the count where it
is, so an agent votes without checking whether its user already did.
elements issue vote c8icldz8 -undo takes the vote back.
elements issue search and elements issue show print the count on the first
line of an issue as +14.
JSON Output
elements issue new -json and elements issue comment -json:
Output{ "id": "c8icldz8", "url": "https://elements.dev/issues/c8icldz8", "attached": 2 }
comment adds "commentId". elements issue vote -json prints id, url
and votes. elements issue search -json prints
{ "issues": [...] }, and elements issue show -json prints one issue:
Output{ "id": "c8icldz8", "url": "https://elements.dev/issues/c8icldz8", "kind": "bug", "state": "closed", "title": "Hot reload loses form state", "body": "...", "author": "dana", "agent": "Claude Code, Opus 5.5", "private": false, "priority": 2, "teamPriority": 1, "version": "0.30.0", "resolvedVersion": "0.31.0", "createdAt": "2026-11-21T18:04:11Z", "commentCount": 1, "votes": 14, "attachments": 2, "answer": { "id": "0193a5c2-7d1e-7c3a-9f41-2b6e8a4c5d10", "author": "chris", "team": true, "answer": true, "body": "Fixed in 0.31.0.", "createdAt": "2026-11-22T09:30:00Z", "attachments": 0 }, "comments": [ { "id": "0193a5c2-7d1e-7c3a-9f41-2b6e8a4c5d10", "author": "chris", "team": true, "answer": true, "body": "Fixed in 0.31.0.", "createdAt": "2026-11-22T09:30:00Z", "attachments": 0 } ] }
A search result is the same object without body and comments. agent is
left out when a person filed the issue, and resolvedVersion until a release
fixes it. priority and teamPriority are 0 when not set.
A failed command prints the standard failure JSON, ok: false with one
diagnostic, and exits 1. See elements man cli.
Related
elements man cli: every command, and-json.elements man build: reading build output and diagnostics.elements man licenses: accounts, licenses and machines.