Upstream/waveterm
1
0
Fork 0
mirror of https://github.com/wavetermdev/waveterm.git synced 2024-12-21 16:38:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

update docs for new wsh commands and options (#1246)

Browse Source
This commit is contained in:
Mike Sawka 2024-11-08 12:13:10 -08:00 committed by GitHub
parent b24e2d917d
commit 61719344e8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 161 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/docs/config.mdx
View File

@ -13,9 +13,11 @@ use ":" as level separators.
:::info
If you installed Wave pre-v0.9.0 your configuration file will be located at
`~/.waveterm/config/settings.json`. This includes all of the other configuration
files as well: `termthemes.json`, `presets.json`, and `widgets.json`.
The easiest way to edit your config files is to use the wsh editconfig command which will open your Wave config file in our built-in preview editor.
```
wsh editconfig
```
:::
@ -81,13 +83,25 @@ For reference this is the current default configuration (v0.8.8):
}
```
:::warning
If you installed Wave pre-v0.9.0 your configuration file will be located at
`~/.waveterm/config/settings.json`. This includes all of the other configuration
files as well: `termthemes.json`, `presets.json`, and `widgets.json`.
:::
### Terminal Theming
User-defined terminal themes are located in `~/.config/waveterm/termthemes.json`. This JSON file is structured as an object, with each sub-key defining a theme.
User-defined terminal themes are located in `~/.config/waveterm/termthemes.json`.
This JSON file is structured as an object, with each sub-key defining a theme.
Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to
the block's metadata key `term:theme`. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).
`wsh setmeta this term:theme="default-dark"`
```
wsh setmeta this term:theme="default-dark"
```
Here is an example of defining a full terminal theme. All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)
@ -122,6 +136,16 @@ Here is an example of defining a full terminal theme. All of the built-in themes
}
```
:::info
You can easily open the termthemes.json config file by running:
```
wsh editconfig termthemes.json
```
:::
| Key Name | Type | ANSI FG# | ANSI BG# | Function |
| ------------------- | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| display:name | string | | | the name as it will appear in the UI context menu |

6
docs/docs/faq.mdx
View File

@ -8,7 +8,8 @@ title: "FAQ"
### How do I set up my own LLM?
You must manually edit the [config file](./config) located at `~/.config/waveterm/settings.json`.
Open your [config file](./config) in Wave using `wsh editconfig` (the config file is normally located
at `~/.config/waveterm/settings.json`).
| Key Name | Type | Function |
| ------------ | ------ | ----------------------------------------------- |
@ -36,7 +37,8 @@ Here are the ollma open AI compatibility docs: https://github.com/ollama/ollama/
### How can I connect to Azure AI
You must manually edit the [config file](./config) located at `~/.config/waveterm/settings.json`.
Open your [config file](./config) in Wave using `wsh editconfig` (the config file is normally located
at `~/.config/waveterm/settings.json`).
You'll need to set your `ai:baseurl` to your Azure AI Base URL (do not include query parameters or `api-version`).
You'll also need to set `ai:apitype` to `azure`. You can then set the `ai:model`, and `ai:apitoken` appropriately

80
docs/docs/telemetry.mdx
View File

@ -4,23 +4,36 @@ id: "telemetry"
title: "Telemetry"
---
Wave Terminal collects telemetry data to help us track feature use, direct future product efforts, and generate aggregate metrics on Wave's popularity and usage. We do not collect or store any PII (personal identifiable information) and all metric data is only associated with and aggregated using your randomly generated _ClientId_. You may opt out of collection at any time.
Wave Terminal collects telemetry data to help us track feature use, direct future product efforts, and generate aggregate metrics on Wave's popularity and usage. We do not collect or store any PII (personal identifiable information) and all metric data is only associated with and aggregated using your randomly generated _ClientId_. You may opt out of collection at any time.
If you would like to turn telemetry on or off, the first opportunity is a button on the initial welcome page. After this, it can be turned off by adding `"telemetry:enabled": false` to the `config/settings.json` file. It can alternatively be turned on by adding `"telemetry:enabled": true` to the `config/settings.json` file.
:::info
You can also change your telemetry setting by running the wsh command:
```
wsh setconfig telemetry:enabled=true
```
:::
---
## Sending Telemetry
Provided that telemetry is enabled, it is sent 10 seconds after Waveterm is first booted and then again every 4 hours thereafter. It can also be sent in response to a few special cases listed below. When telemetry is sent, it is grouped into individual days as determined by your time zone. Any data from a previous day is marked as `Uploaded` so it will not need to be sent again.
### Sending Once Telemetry is Enabled
As soon as telemetry is enabled, a telemetry update is sent regardless of how long it has been since the last send. This does not reset the usual timer for telemetry sends.
### Notifying that Telemetry is Disabled
As soon as telemetry is disabled, Waveterm sends a special update that notifies us of this change. See [When Telemetry is Turned Off](#when-telemetry-is-turned-off) for more info. The timer still runs in the background but no data is sent.
### When Waveterm is Closed
Provided that telemetry is enabled, it will be sent when Waveterm is closed.
---
@ -29,42 +42,44 @@ Provided that telemetry is enabled, it will be sent when Waveterm is closed.
When telemetry is active, we collect the following data. It is stored in the `telemetry.TelemetryData` type in the source code.
| Name | Description |
|------|-------------|
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ActiveMinutes | The number of minutes that the user has actively used Waveterm on a given day. This requires the terminal window to be in focus while the user is actively interacting with it. |
| FgMinutes | The number of minutes that Waveterm has been in the foreground on a given day. This requires the terminal window to be in focus regardless of user interaction.|
| OpenMinutes |The number of minutes that Waveterm has been open on a given day. This only requires that the terminal is open, even if the window is out of focus.|
| NumTabs | The number of existing tabs open on a given day. |
| NewTab | The number of new tabs opened on a given day. |
| NumStartup | The number of times waveterm has been started on a given day. |
| NumShutdown | The number of times waveterm has been shut down on a given day. |
| Renderers | The number of new block views of each type are open on a given day. |
| FgMinutes | The number of minutes that Waveterm has been in the foreground on a given day. This requires the terminal window to be in focus regardless of user interaction. |
| OpenMinutes | The number of minutes that Waveterm has been open on a given day. This only requires that the terminal is open, even if the window is out of focus. |
| NumTabs | The number of existing tabs open on a given day. |
| NewTab | The number of new tabs opened on a given day. |
| NumStartup | The number of times waveterm has been started on a given day. |
| NumShutdown | The number of times waveterm has been shut down on a given day. |
| Renderers | The number of new block views of each type are open on a given day. |
## Associated Data
In addition to the telemetry data collected, the following is also reported. It is stored in the `telemetry.ActivityType` type in the source code.
| Name | Description |
|------|-------------|
| Day | The date the telemetry is associated with. It does not include the time. |
| Uploaded | A boolean that indicates if the telemetry for this day is finalized. It is false during the day the telemetry is associated with, but gets set true at the first telemetry upload after that. Once it is true, the data for that particular day will not be sent up with the telemetry any more. |
| TzName | The code for the timezone the user's OS is reporting (e.g. PST, GMT, JST) |
| TzOffset | The offset for the timezone the user's OS is reporting (e.g. -08:00, +00:00, +09:00) |
| ClientVersion | Which version of Waveterm is installed. |
| ClientArch | This includes the user's operating system (e.g. linux or darwin) and architecture (e.g. x86_64 or arm64). It does not include data for any Connections at this time. |
| BuildTime | This serves as a more accurate version number that keeps track of when we built the version. It has no bearing on when that version was installed by you.|
| OSRelease | This lists the version of the operating system the user has installed. |
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Day | The date the telemetry is associated with. It does not include the time. |
| Uploaded | A boolean that indicates if the telemetry for this day is finalized. It is false during the day the telemetry is associated with, but gets set true at the first telemetry upload after that. Once it is true, the data for that particular day will not be sent up with the telemetry any more. |
| TzName | The code for the timezone the user's OS is reporting (e.g. PST, GMT, JST) |
| TzOffset | The offset for the timezone the user's OS is reporting (e.g. -08:00, +00:00, +09:00) |
| ClientVersion | Which version of Waveterm is installed. |
| ClientArch | This includes the user's operating system (e.g. linux or darwin) and architecture (e.g. x86_64 or arm64). It does not include data for any Connections at this time. |
| BuildTime | This serves as a more accurate version number that keeps track of when we built the version. It has no bearing on when that version was installed by you. |
| OSRelease | This lists the version of the operating system the user has installed. |
## Telemetry Metadata
Lastly, some data is sent along with the telemetry that describes how to classify it. It is stored in the `wcloud.TelemetryInputType` in the source code.
| Name | Description |
|------|-------------|
| UserId | Currently Unused. This is an anonymous UUID intended for use in future features. |
| ClientId | This is an anonymous UUID created when Waveterm is first launched. It is used for telemetry and sending prompts to Open AI.
| AppType | This is used to differentiate the current version of waveterm from the legacy app. |
| AutoUpdateEnabled | Whether or not auto update is turned on. |
| AutoUpdateChannel | The type of auto update in use. This specifically refers to whether a latest or beta channel is selected. |
| CurDay | The current day (in your time zone) when telemetry is sent. It does not include the time of day.
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| UserId | Currently Unused. This is an anonymous UUID intended for use in future features. |
| ClientId | This is an anonymous UUID created when Waveterm is first launched. It is used for telemetry and sending prompts to Open AI. |
| AppType | This is used to differentiate the current version of waveterm from the legacy app. |
| AutoUpdateEnabled | Whether or not auto update is turned on. |
| AutoUpdateChannel | The type of auto update in use. This specifically refers to whether a latest or beta channel is selected. |
| CurDay | The current day (in your time zone) when telemetry is sent. It does not include the time of day. |
---
@ -75,14 +90,17 @@ When a user disables telemetry, Waveterm sends a notification that their anonymo
---
## A Note on IP Addresses
Telemetry is uploaded via https, which means your IP address is known to the telemetry server. We **do not** store your IP address in our telemetry table and **do not** associate it with your _ClientId_.
Telemetry is uploaded via https, which means your IP address is known to the telemetry server. We **do not** store your IP address in our telemetry table and **do not** associate it with your _ClientId_.
---
## Previously Collected Telemetry Data
While we believe the data we collect with telemetry is fairly minimal, we cannot make that decision for every user. If you ever change your mind about what has been collected previously, you may request that your data be deleted by emailing us at [support@waveterm.dev](mailto:support@waveterm.dev). If you do, we will need your _ClientId_ to remove it.
---
## Privacy Policy
For a summary of the above, you can take a look at our [Privacy Policy](https://www.waveterm.dev/privacy).
For a summary of the above, you can take a look at our [Privacy Policy](https://www.waveterm.dev/privacy).

90
docs/docs/wsh.mdx
View File

@ -3,20 +3,27 @@ sidebar_position: 4
id: "wsh"
title: "wsh command"
---
import { Kbd } from "@site/src/components/kbd.tsx";
import { PlatformProvider, PlatformToggleButton } from "@site/src/components/platformcontext.tsx";
<PlatformProvider>
# wsh command
The `wsh` command is always available from Wave blocks. It is a powerful tool for interacting with Wave blocks and can bridge data between your CLI and the widget GUIs.
The `wsh` command is always available from Wave blocks. It is a powerful tool for interacting with Wave blocks and can bridge data between your CLI and the widget GUIs.
---
## view
You can open a preview block with the contents of any file or directory by running:
```
wsh view [path]
```
You can use this command to easily preview images, markdown files, and directories. For code/text files this will open
You can use this command to easily preview images, markdown files, and directories. For code/text files this will open
a codeedit block which you can use to quickly edit the file using Wave's embedded graphical editor.
---
@ -27,45 +34,95 @@ a codeedit block which you can use to quickly edit the file using Wave's embedde
wsh edit [path]
```
This will open up codeedit for the specified file. This is useful for quickly editing files on a local or remote machine in our graphical editor. This command will wait until the file is closed before exiting (unlike \`view\`) so you can set your \`$EDITOR\` to \`wsh editor\` for a seamless experience. You can combine this with a \`-m\` flag to open the editor in magnified mode.
This will open up codeedit for the specified file. This is useful for quickly editing files on a local or remote machine in our graphical editor. This command will wait until the file is closed before exiting (unlike \`view\`) so you can set your \`$EDITOR\` to \`wsh editor\` for a seamless experience. You can combine this with a \`-m\` flag to open the editor in magnified mode.
---
## getmeta
You can view the metadata of any block by running:
You can view the metadata of any block or tab by running:
```
# get the metadata for the current terminal block
wsh getmeta
# get the metadata for block num 2 (see block numbers by holidng down Ctrl+Shift)
wsh getmeta -b 2
# get the metadata for a blockid (get block ids by right clicking any block header "Copy Block Id")
wsh getmeta -b [blockid]
# get the metadata for a tab
wsh getmeta -b tab
# dump a single metadata key
wsh getmeta [-b [blockid]] [key]
# dump a set of keys with a certain prefix
wsh getmeta -b tab "bg:*"
# dump a set of keys with prefix (and include the 'clear' key)
wsh getmeta -b tab --clear-prefix "bg:*"
```
This is especially useful for preview and web blocks as you can see the file or url that they are pointing to and use that in your CLI scripts.
blockid format:
* this -- the current block (this is also the default)
* tab -- the id of the current tab
* d6ff4966-231a-4074-b78a-20acc7226b41 -- a full blockid is a UUID
* a67f55a3 -- blockids may be truncated to the first 8 characters
* 5 -- if a number less than 100 is given, it is a block number. blocks are numbered sequentially in the current tab from the top-left to bottom-right. holding Ctrl:Shift will show a block number overlay.
- `this` -- the current block (this is also the default)
- `tab` -- the id of the current tab
- `d6ff4966-231a-4074-b78a-20acc7226b41` -- a full blockid is a UUID
- `a67f55a3` -- blockids may be truncated to the first 8 characters
- `5` -- if a number less than 100 is given, it is a block number. blocks are numbered sequentially in the current tab from the top-left to bottom-right. holding <Kbd k="Ctrl:Shift"/> will show a block number overlay.
---
## setmeta
You can update any metadata key value pair for blocks (and tabs) by using the setmeta command:
You can update any metadata key value pair for blocks (and tabs) by using the setmeta command. The setmeta command takes the same `-b` arguments as getmeta.
```
wsh setmeta -b [blockid] [key]=[value]
wsh setmeta -b [blockid] file=~/myfile.txt
wsh setmeta -b [blockid] url=https://waveterm.dev/
# set the metadata for the current tab using the given json file
wsh setmeta -b tab --json [jsonfile]
# set the metadata for the current tab using a json file read from stdin
wsh setmeta -b tab --json
```
You can get block and tab ids by right clicking on the appropriate block and selecting "Copy BlockId" (or use the block number via Ctrl:Shift). When you
You can get block and tab ids by right clicking on the appropriate block and selecting "Copy BlockId" (or use the block number via Ctrl:Shift). When you
update the metadata for a preview or web block you'll see the changes reflected instantly in the block.
Other useful metadata values to override block titles, icons, colors, themes, etc.
Here's a complex command that will copy the background (bg:\* keys) from one tab to the current tab:
```
wsh getmeta -b [other-tab-id] "bg:*" --clear-prefix | wsh setmeta -b tab --json -
```
---
## editconfig
You can easily open up any of Wave's config files using this command.
```
wsh editconfig [config-file-name]
# opens the default settings.json file
wsh editconfig
# opens presets.json
wsh editconfig presets.json
# opens widgets.json
wsh editconfig widgets.json
```
---
## deleteblock
@ -125,16 +182,19 @@ This has several subcommands which all perform various features related to conne
```
wsh conn status
```
This command gives the status of all connections made since waveterm started.
### reinstall
For ssh connections,
```
wsh conn reinstall [user@host]
```
For wsl connections,
```
wsh conn reinstall [wsl://<distribution name>]
```
@ -144,11 +204,13 @@ This command reinstalls the Wave Shell Extensions on the specified connection.
### disconnect
For ssh connections,
```
wsh conn disconnect [user@host]
```
For wsl connections,
```
wsh conn disconnect [wsl://<distribution name>]
```
@ -158,11 +220,13 @@ This command completely disconnects the specified connection. This will apply to
### connect
For ssh connections,
```
wsh conn connect [user@host]
```
For wsl connections,
```
wsh conn connect [wsl://<distribution name>]
```
@ -172,11 +236,13 @@ This command connects to the specified connection but does not create a block fo
### ensure
For ssh connections,
```
wsh conn ensure [user@host]
```
For wsl connections,
```
wsh conn ensure [wsl://<distribution name>]
```
@ -192,3 +258,5 @@ wsh setconfig [config name]=[config value]
```
This allows setting various options in the `config/settings.json` file. It will check to be sure a valid config option was provided.
</PlatformProvider>