# Issues `elements 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 ```bash Terminal elements 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: ```bash Terminal elements 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 test` or `elements 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: ```bash Terminal elements 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 `elements` version, 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 ```bash Terminal elements 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: ```bash Terminal elements 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 ```bash Terminal elements 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 `-attach` are sent. `elements issue` reads 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 ```bash Terminal elements 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 ```bash Terminal elements 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 ```bash Terminal elements 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`: ```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: ```json 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.