Positron Commands

Positron IDE commands

These commands act on the Positron workbench itself -- layout, panes, editors, interpreter sessions, and packages. They do not run interpreter code; use executeCode for that.

Calling these commands

Invoke commands with the positronCommand tool, passing the command's literal id exactly as written in the reference files -- copy it, do not retype it from memory. Where a command takes arguments, fill args positionally in the order given under that command's "Arguments" entry. Omit args entirely for commands that take none -- do not pass an empty object or array. Never invent an argument value the user hasn't given you or that isn't documented; if a required value is unknown, ask the user first.

Find the id here before you run it. Positron is built on VS Code, so a plausible-sounding VS Code command id usually does exist and will usually run -- which makes recalling one from memory the most expensive mistake available. Some ids that read like they do the thing directly instead open a dialog or a quick-pick and wait for the user to choose, so the command "succeeds" while handing the task straight back to them. Read the relevant reference file first and use the id and arguments it gives you. If what the user wants is not covered by any file below, say so rather than reaching for an id from general VS Code knowledge.

Some commands take or return an internal id -- a runtime id or a session id. These are opaque handles you pass back into another command; they are not shown anywhere in the Positron UI, so a user won't recognize one and it would only confuse them. Use ids to make the call, but never repeat one to the user. Refer to a session or interpreter by its name instead.

When a command doesn't work

• disabled: the command's precondition doesn't currently hold. Common causes are no running interpreter session, or no Data Explorer editor open. Report this plainly (e.g. "there's no Data Explorer editor open right now") rather than retrying or guessing at a workaround. Each reference file notes which of its commands have preconditions.
• not-found: the command id isn't present in this Positron build, meaning the build is older or newer than this skill expects. Report this plainly; do not substitute a similarly named id you're unsure about.

Reference Files

Load the file covering the area in question -- the command ids, arguments, and return values live there, not in this file.

UI, layout and panes -- references/ui.md Read when the user asks about: switching the workbench layout (four-pane, notebook, two-pane), bringing a pane into focus (Console, Variables, Help, Plots, Packages), clearing console output, or expanding/collapsing the Data Explorer's column summary panel.

Opening files -- references/files.md Read when the user wants a file open in Positron: "open data.csv", "show me that file", "let's look at this CSV/Parquet/Excel file", or anything that should land in the Data Explorer. Read it before opening anything -- it documents the one command that opens a known path, and names the similar-looking ids that open a file picker instead and hand the task back to the user.

Registered interpreters -- references/interpreters.md Read when the user asks what interpreters are available, wants the registered interpreters listed (Python, R, or another language), or needs Positron to rescan for newly installed environments. Also the place to find a base interpreter before creating an environment.

Sessions -- references/sessions.md Read when the user asks about: which sessions are running, switching to a different session, or starting a new one. Also explains the difference between console sessions and notebook sessions, which decides whether a session can be selected.

Stuck sessions and help -- references/troubleshooting.md Read when the user asks about a session that is stuck, needs interrupting, or needs restarting. Also covers looking up a help topic for a function or symbol.

Packages -- references/packages.md Read when the user asks about: what is installed in a session and at which version, whether a package is available, out of date or affected by a known security advisory, or installing and updating packages. Read it before answering any question about what the session has -- it documents the command that reports the installed packages, which is always the right way to find out, rather than running code to check.

Python environment setup -- references/python-setup.md Read when the user is getting Python set up: installing a Python interpreter when they have none, creating a project environment (venv, Conda, or uv), or finding out which interpreter is currently active.

Interactive web apps -- references/interactive-apps.md Read when the user wants a web app running or debugged: "run my app", "start the shiny/flask/dash/streamlit/marimo app", "preview my dashboard". Read it before starting any app server yourself -- app servers must not be started via executeCode or a raw terminal command for supported app frameworks. The commands it documents manage the terminal, detect the app URL, set up any proxying the environment requires (on Posit Workbench, raw localhost URLs are not reachable from the user's browser), and preview the app -- in the Viewer by default, or wherever the user's preview mode setting points.