Skip to content

Commit 7f29568

Browse files
EhabYEhabY
authored
docs: document URI handler format in README (#997)
Adds a `URI Handler` section to the README documenting the `/open` and `/openDevContainer` paths with parameter tables, based on `src/uri/uriHandler.ts`. Closes [DEVEX-451](https://linear.app/codercom/issue/DEVEX-451/document-vs-code-extension-uri-format-in-readme).
1 parent 0f29224 commit 7f29568

1 file changed

Lines changed: 40 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,43 @@ Alternatively, manually install the VSIX from the
5151
All extension settings are under the `coder.*` namespace in the Settings UI.
5252
Paths in settings accept `~` and `${userHome}` from VS Code's
5353
[variables reference](https://code.visualstudio.com/docs/editor/variables-reference).
54+
55+
## URI Handler
56+
57+
The extension registers a URI handler that can open workspaces from outside
58+
the editor, such as links on the Coder dashboard. The scheme matches the
59+
editor (`vscode://`, `cursor://`, `windsurf://`, etc.), followed by the
60+
extension ID and a path:
61+
62+
```text
63+
vscode://coder.coder-remote/open?owner=alice&workspace=dev&agent=main&folder=/home/coder/project
64+
```
65+
66+
### `/open`
67+
68+
Opens a workspace, starting it first if needed.
69+
70+
| Parameter | Required | Description |
71+
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72+
| `owner` | Yes | Username of the workspace owner. |
73+
| `workspace` | Yes | Name of the workspace. |
74+
| `agent` | No | Agent _name_ (not ID). If omitted or unmatched in a multi-agent workspace, a picker is shown. |
75+
| `folder` | No | Absolute path inside the workspace to open. If omitted, a recently opened folder for this workspace is used (a picker is shown when there are several); with no recents, the window opens without a folder. |
76+
| `openRecent` | No | Open the most recently used folder for this workspace, skipping the picker. True when present without a value or set to `true`. Ignored when `folder` is set. |
77+
| `url` | No | Coder deployment URL. If omitted, the extension prompts for it (pre-filled with the current deployment). |
78+
| `token` | No | Session token for authentication. If omitted, the existing session is used or a login flow is started. |
79+
80+
### `/openDevContainer`
81+
82+
Opens a dev container running inside a workspace.
83+
84+
| Parameter | Required | Description |
85+
| ---------------------- | -------- | ------------------------------------------------------------------------------ |
86+
| `owner` | Yes | Username of the workspace owner. |
87+
| `workspace` | Yes | Name of the workspace. |
88+
| `agent` | Yes | Agent name the dev container runs on. |
89+
| `devContainerName` | Yes | Name of the dev container. |
90+
| `devContainerFolder` | Yes | Folder to open inside the dev container. |
91+
| `localWorkspaceFolder` | No | Local path of the dev container project. Required if `localConfigFile` is set. |
92+
| `localConfigFile` | No | Local path to the `devcontainer.json` file. |
93+
| `url`, `token` | No | Same as `/open`. |

0 commit comments

Comments
 (0)