Debugging
A set of commands connects to a running acdev dev session and lets you look at pages, run code, take screenshots, and click buttons. acdev devtools also opens the DevTools of Chrome or Edge on a page; see DevTools. Run them in another terminal:
acdev websNAME KIND APP WINDOW TITLEdesktop desktop - 0 My Desktopnotes#1048576 app notes 1048576 NotesSessions
Section titled “Sessions”These commands find an acdev dev session in this order: --session <pid>; otherwise the session whose project directory contains the current directory; otherwise, outside any project, the only session, if there is just one (the command then names it on stderr: acdev: using acdev dev <pid> (...), the only one running); otherwise they fail and list all sessions. Sessions that acdev test started for its tests are left out of this choice (they are listed with acdev test after what they run); only --session <pid> reaches them.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
acdev webs |
Lists the running pages (one per window) |
acdev eval <web> <code> |
Runs code in a page and prints the result as JSON; Promises are awaited. With - as the code, reads it from stdin |
acdev shot <web> [-o FILE] |
Screenshot of one window's page (PNG); for desktop, without the panels it pins (Dock, menu bar), which acdev screen shows |
acdev screen [-o FILE] |
Screenshot of the whole screen, all windows together |
acdev pointer <x> <y> |
Moves the pointer to a point on the screen, as a real move: hover effects and screen edge events (a desktop showing its Dock at an edge) follow. In a host window the screen is its content area |
acdev inspect [--window W] [--find TEXT] [--all] [--offscreen] |
Turns the screen into text: the window list and the element tree of the focused window (--all: every window that is not marked [minimized], and elements hidden by opacity: 0 or visibility) |
acdev query <selector> [--window W] [--ref REF] [--limit N] |
Finds elements by CSS selector, including ones inspect leaves out, and prints a ref for each |
acdev act <ref> <action> [arg] |
Clicks, types, presses keys, and more on a ref from inspect or query |
acdev console [--web W] [--level L] [--since S] [--follow] |
The pages' console.* output and uncaught errors |
acdev network [--web W] [--failed] [--since S] [--follow] |
The pages' fetch / XHR / WebSocket / EventSource requests and their image, stylesheet and font loads; the kind column says which |
acdev permissions |
Lists the camera and microphone prompts that wait and the decisions made; see Camera and microphone |
acdev allow / acdev deny [<prompt id> | <app> <capability>] [--all] |
Answers a waiting camera or microphone prompt |
acdev revoke <app> <capability> |
Takes back a decision |
acdev stop |
Ends the session; see Stopping |
acdev devtools [web] |
Opens the DevTools of Chrome or Edge on a page; see DevTools |
A web is one page: the desktop page, or the page in one app window (each window has one). <web> is a web name from acdev webs (notes#1048576), an app id (that app's first window), or desktop. In a Dopame OS guest, a page that does not answer within 1.5 s (its process is stopped or busy) is still listed, with the title (not answering); the other pages are listed as usual.
acdev eval notes 'document.title'acdev eval notes 'import("acde:fs").then(m => m.fs.roots())'echo 'localStorage.length' | acdev eval notes -On Windows, acdev is acde.cmd, so what reaches the CLI is what cmd makes of the arguments. What a shell passes differs:
- PowerShell (5.1 and 7) drops double quotes inside arguments it passes to a
.cmd; write them as\"(the first line below). - cmd has no single-quoted strings: put the argument in double quotes and write the double quotes inside it as
\"(the second line below).
acdev eval notes 'document.querySelector(\"#x\").textContent'acdev eval notes "document.querySelector(\"#x\").textContent"Code that has only single quotes inside it is written the same way in all three, and passing the code on stdin avoids the question (shown for PowerShell):
acdev eval notes "document.querySelector('#x').textContent"'document.querySelector("#x").textContent' | acdev eval notes -The same applies to any argument with double quotes, such as act ... type.
inspect and act
Section titled “inspect and act”inspect gives every element a ref, such as w1.18 (element 18 in window w1); pass it to act.
$ acdev inspect- window "Notes" [app=notes] [focused] [fullscreen] [w1] - heading "Notes" [level=1] [w1.16] - form [w1.6] - text "Title" [w1.17] - textbox "Title": "" [w1.18] - text "Email" [w1.19] - textbox "Email": "" [w1.20] - button "Save" [w1.21] - list "Saved notes" [w1.7] - listitem [w1.22] - text "Buy milk" [w1.22] - text "1 note" [w1.8] (1 more outside the visible area; scroll, or add offscreen)
$ acdev act w1.18 type "Weekly report"typed, the value is now "Weekly report"
(windows unchanged)- window "Notes" [app=notes] [focused] [fullscreen] [w1] ~ - textbox "Title": "Weekly report" [focused] [w1.18] (1 more outside the visible area; scroll, or add offscreen)
$ acdev act w1.21 clickclicked 55,202
(windows unchanged)- window "Notes" [app=notes] [focused] [fullscreen] [w1] ~ - textbox "Title": "" [w1.18] ~ - button "Save" [focused] [w1.21] + - listitem [w1.23] + - text "Weekly report" [w1.23] ~ - text "2 notes" [w1.8] (1 more outside the visible area; scroll, or add offscreen)Without --find, the text is always in this English format: one line per window, top first (- window "Notes" [app=notes] [focused] [w1], the desktop is - desktop), and under a listed window its elements, indented two spaces per level, as - role "name": "value" [states] [ref] (the value only where the element has one). Notes in parentheses say what is left out or unchanged, such as (empty), (no changes) and (windows unchanged).
act prints what it did on the first line (clicked 55,202 is the point it clicked, in window coordinates), waits for the page to settle, and then prints the windows and the content of the window again. Where it has listed that window before, it prints only what changed since: ~ for a changed line, + for a new one, - for one that is gone; (windows unchanged) stands for an unchanged window list. So the output of act is usually all you need to read before the next step. An element that is scrolled out of view is scrolled into view first, so a ref from inspect --offscreen or query works wherever the element is on the page.
act exits with code 0 when the action was done. When it was not, it prints one line on stderr, acdev: act <ref>: <reason>, and exits with code 1. The reasons: the element is not displayed (it is display: none or hidden by visibility), covered by another element: <div> (27), cannot type into this element, there is no such element (any more); acdev inspect --find TEXT gives the current refs (the element is gone, see below), w1 is minimized; act restore on it first (a click or another pointer action on a minimized window or on an element in it).
A ref stays the same as long as its element lives: moving it, changing its text or attributes, or reordering a list keeps it. When the page replaces the element with a new one (for example by setting innerHTML), the new element gets a new ref, and acting on the old one fails (acdev: act w1.23: there is no such element (any more); …); take a new inspect then.
An app run on its own shows its window menus on the title bar (see Windows), and inspect lists them first: menubar [w1.m], one menuitem "File" [collapsed] [w1.m1] per menu, and under the open one its items with their shortcuts, menuitem "New": "ctrl+n" [w1.m1.1] (a separator takes a number too). acdev act w1.m1 click opens a menu, acdev act w1.m1.1 click opens it if needed and chooses the item (chose File › New), and acdev act w1 key escape closes it. A disabled item is not chosen (acdev: act w1.m1.4: w1.m1.4 (Print) is disabled).
By default the tree leaves out elements that can't be seen: display: none, aria-hidden, inert, opacity: 0 and hidden visibility. --all lists every window that is not marked [minimized] in the window list and also keeps the elements hidden by opacity: 0 (marked transparent; they can still be clicked) or by visibility (marked invisible; they can't); display: none, aria-hidden and inert are always left out.
A window that is off the screen is marked [minimized] in the window list: one whose state is minimized (after act w1 minimize, the app's own minimize(), or the desktop's windows.requestState(id, 'minimized')), and one the desktop hid with windows.hide(id). Its elements are not listed: --all and --find skip it, and --window w1 prints (empty) and (minimized; act restore on it to see its elements) under its line. Pointer actions on it (click, double, right, hover, scroll, and drag from or onto it) are refused, and act w1 restore brings it back. In a desktop session:
$ acdev act w1 minimizew1 is minimized (the windows changed)
- window "Tools" [app=tools] [minimized] [w1]- desktop [focused] [fullscreen] [w0] - navigation "Apps" [w0.6] - button "Tools" [w0.10]
$ acdev act w1.10 clickacdev: act w1.10: w1 is minimized; act restore on it first
$ acdev act w1 restorew1 is in front (the windows changed)
- window "Tools" [app=tools] [focused] [w1] + - heading "Tools" [level=1] [w1.10]- desktop [fullscreen] [w0]--find TEXT looks in every window that is not marked [minimized] (or in --window W) and prints only the elements whose name or value contains the text (case does not matter). Its output has a format of its own: a line <window ref> <app id> "<title>": for each window that has a match (w0 desktop: for the desktop), and under it one line per element. An element inside an ancestor that has a name is followed by in and the nearest such ancestor; one that has none is followed by nothing:
$ acdev inspect --find milkw1 notes "Notes":- text "Buy milk" [w1.22] in list "Saved notes" [w1.7]
$ acdev inspect --find savew1 notes "Notes":- button "Save" [w1.21]- list "Saved notes" [w1.7]When nothing matches it says so on stderr (acdev: no element's name or value contains "milk"; elements scrolled out of view need --offscreen) and exits with code 2. Elements scrolled out of view are found only with --offscreen; without it, a note under the tree says how many were left out ((1 more outside the visible area; scroll, or add offscreen)).
Actions: click double right hover scroll type settext select key drag focus; a window ref (w1) also accepts close minimize restore fill fullscreen. fill fills the desktop's work area with the window and fullscreen covers the whole host window with it; restore sets either back to normal. Both refuse the desktop (the desktop cannot be made filled, ... fullscreen) and a window that already fills the host window (w1 already fills the host window). minimize on a window that cannot be minimized changes nothing, says why and exits with code 1; in a session that runs a single app, on macOS and headless, that is the app's own window: w1 cannot be minimized: it fills the host window, which only the host window's own controls minimize here. The argument to key looks like "ctrl+a backspace"; the argument to drag is the target ref. When closing a window ends acdev runtime (the app's window when acdev dev runs one app), acdev dev ends with it; act w1 close then says so and exits with code 0.
Key names
Section titled “Key names”The argument to key (and press() in tests) is one or more chords separated by spaces; a chord is keys joined by +, pressed in order and released in reverse. Keys are physical keys on a US layout. Case does not matter, except that a single capital letter (A) adds shift:
- modifiers:
ctrl(control),shift,alt,super(meta,win) - letters
a…z, digits0…9,f1…f12 enter(return),escape(esc),tab,space,backspace,delete(del),insert,home,end,pageup,pagedown,up,down,left,right,menu- printable characters as they are:
-=[];'`\,./, and the shifted ones!@#$%^&*()_+{}|:"<>?~, which addshiftthemselves (*isshift+8).+alone, or last in a chord (ctrl++), is the+key - names for some characters:
plus(+),multiply,asterisk,star(*),minus(-),divide(/),period(.),comma(,); these are the main keyboard keys, not the keypad - the keypad:
Numpad0…Numpad9,NumpadAdd,NumpadSubtract,NumpadMultiply,NumpadDivide,NumpadDecimal,NumpadEnter - the DOM
KeyboardEvent.codenames of the other keys, e.g.KeyA,Digit8,Minus,ArrowUp,CapsLock,ShiftRight
The whole argument is checked before anything is pressed: an unknown key fails with unknown key: … and presses nothing. The space character is space (spaces separate chords). To enter text, use type instead.
inspect lists what a user can see and use. query finds elements by CSS selector whether they are shown or not, and gives each a ref, so it reaches what inspect leaves out: an element that is display: none, one that is scrolled out of view, and one that has no role, name or value of its own (a plain <div>; inspect lists what is inside it in its place).
$ acdev query 'form input[type=email]'1 in w1:- textbox "Email": "" [w1.20] <input>
$ acdev query '[data-testid="menu"] li'2 in w1:- generic "Rename" [w1.25] <li> [hidden]- generic "Delete" [w1.26] <li> [hidden]
$ acdev query button4 in w1:- button "Save" [focused] [w1.21] <button>- button "Undo" [transparent] [w1.10] <button> [hidden]- button [invisible] [w1.24] <button> [hidden]- button "Load more" [w1.11] <button>
$ acdev query navacdev: nothing in w1 matches "nav"Each line is the element's role, name, value, a heading's level, states and ref, exactly as inspect prints them (- heading "Notes" [level=1] [w1.16] <h1>), then its tag. [hidden] after the tag marks an element that is not visible: it has no size, or is display: none, hidden by visibility, or transparent, or its window is minimized. The transparent and invisible marks are the ones inspect --all gives: a transparent element still takes clicks, as it does for a user; for an invisible or display: none one, act answers the element is not displayed until the page shows it. An element whose role cannot be told is listed as generic; the tag says what it is.
The refs work with act, like the ones from inspect: acdev act w1.20 type "me@example.com". query searches the focused window; --window w2 picks another, --ref w1.6 searches only under that element, and --limit N lists at most N elements (1 to 3000, default 600; the first line still counts them all). When nothing matches, it says so on stderr (acdev: nothing in w1 matches "nav") and the exit code is 2; otherwise it is 0.
Styles and layout
Section titled “Styles and layout”To look at styles and boxes, ask the page with eval (or the Elements panel of DevTools). getComputedStyle gives the values the page uses after the CSS cascade, and getBoundingClientRect gives an element's box in CSS pixels of the page:
acdev eval notes "getComputedStyle(document.querySelector('h1')).color"acdev eval notes "(({ display, fontSize, margin }) => ({ display, fontSize, margin }))(getComputedStyle(document.querySelector('.card')))"acdev eval notes "(({ x, y, width, height }) => ({ x, y, width, height }))(document.querySelector('.card').getBoundingClientRect())"Copy the properties you want into a plain object, as above, so the JSON result has them. The code has only single quotes inside, so it is written the same way in sh, PowerShell and cmd (see eval). To see whether something is drawn where you expect, take a screenshot with acdev shot; to find an element that inspect leaves out (no size, display: none), use acdev query.
console and network
Section titled “console and network”acdev console --level errors --followacdev network --failed--level is log, info, warn, error, debug, or errors (console.error plus uncaught errors). --follow keeps printing new entries.
When a fetch in the page rejects with TypeError: Failed to fetch, the line of that request in acdev network --failed says why (a CORS rule, a name that does not resolve, a refused connection):
$ acdev network --failed 1 GET ERR https://nonexistent.invalid/ (fetch 158 ms; Failed to connect to host: Failed resolving hostname: failed to lookup address information: nodename nor servname provided, or not known) notes#1048576Entries stay after a page reloads, so errors from before a change are still listed. The first column is the entry's number. --since reload lists only what came after acdev dev last rebuilt and reloaded (everything, if it has not reloaded yet); --since N lists entry N and later. A reload the page does by itself (location.reload()) does not count.
acdev console --level errors --since reloadThe most recent 5000 entries of each kind are kept.
DevTools
Section titled “DevTools”acdev devtools [web] opens the DevTools of Chrome or Edge (or Chromium on Linux) on a page of the session: Elements, Console, Network, and Sources with breakpoints.
acdev devtools # the focused pageacdev devtools notes # a web name, an app id, desktop, or a window titleacdev devtools services # the desktop's services (or one service, by its name)It prints the DevTools address on stdout, and on stderr acdev: opened DevTools for <page> in <browser>. Asked again for a page whose DevTools are open, it brings them to the front instead (acdev: brought DevTools for <page> to the front in <browser>). F12 in the host window of acdev dev does the same for the page in that window; see acdev dev.
The browser runs with a profile of acdev's own, not your everyday one. ACDEV_BROWSER names another browser (a path to it). Without Chrome or Edge, or with ACDEV_BROWSER=none, nothing opens: paste the printed address into the address bar of Chrome or Edge on this machine.
Elements shows the element tree, the computed styles and the box model, read only. It does not list the CSS rules that matched an element (only its inline style); change styles from the page code or the Console.
Without a display
Section titled “Without a display”On a machine without a display, such as a server over ssh, start the session with acdev dev --headless. On Linux, acdev dev without it stops at once when neither WAYLAND_DISPLAY nor DISPLAY is set and says to add --headless; see acdev dev. Every command on this page works the same in a headless session:
acdev dev --headless &acdev inspect # the windows and the focused window's elements, as textacdev shot notes # ./notes.pngacdev screen # ./screen.png, every window togetherA headless session has no picker dialogs: a folder, file or save picker the page opens fails unless it was answered beforehand, and the page sees it as cancelled. Answer it from a test with chooseFolder, chooseFiles or chooseSaveFile (Testing), from an agent with the MCP tools choose_folder, choose_files and choose_save_file (MCP), or from the shell with acdev choose folder ~/Notes, acdev choose open a.md b.md or acdev choose save out.md (--cancel to cancel). acdev drop <web> <file...> drops files onto a page, as a drag from the file manager would. The session output names the missing answer: no folder chooser without a host window (ACDE_HEADLESS): answer it beforehand with the MCP tool choose_folder or acde.chooseFolder() in a test. A headless session also has its own clipboard and no camera or microphone dialog (see below).
Camera and microphone
Section titled “Camera and microphone”A capability an app declares is granted without asking, except the camera, the microphone and idle detection (idleDetection). The user is asked the first time a page asks for one (getUserMedia, IdleDetector.requestPermission()), and the call waits for the answer. In a session that runs a single app, the host window asks in a dialog on Windows, on macOS (a sheet with Don't Allow and Allow) and on Linux (a notification with the same two buttons, where the desktop's notification service shows buttons). Elsewhere, and in a headless session, there is no dialog, so answer from the command line:
$ acdev permissionspending: 1 recorder microphone (request)decisions: none
$ acdev allowallowed recorder microphone (prompt 1)Without arguments, acdev allow and acdev deny answer the only waiting prompt. When several wait, they answer none and list them; name one by its id (acdev allow 2) or by app and capability (acdev allow recorder microphone), or answer them all with --all.
Decisions persist per app (in $XDG_CONFIG_HOME/acde/permissions.json), so the user is not asked again. Answering is the user's decision: when you run these commands for someone, allow only what they asked for or agreed to, and tell them what you allowed. acdev revoke <app> <capability> removes a decision, so the app is asked again the next time it asks. A denied or revoked capability makes getUserMedia reject with NotAllowedError, as in a browser.
Errors
Section titled “Errors”When a command fails, it prints acdev: <reason> and exits with code 1. If the session has already exited, it says acdev dev <pid> is gone. inspect --find and query that find nothing are not failures; they exit with code 2.