Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
milesj committed Sep 18, 2023
1 parent 5dedc9e commit e942920
Show file tree
Hide file tree
Showing 4 changed files with 94 additions and 17 deletions.
3 changes: 1 addition & 2 deletions website/docs/proto/commands/plugins.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@ The `proto plugins` command will list all available and configured plugins. Will
```shell
$ proto plugins
bun - Bun v1.2
GitHub: moonrepo/bun-plugin
Tag: latest
Source: https://github.com/moonrepo/bun-plugin/releases/latest/download/bun_plugin.wasm

deno - Deno v2.0
GitHub: moonrepo/deno-plugin
Expand Down
41 changes: 41 additions & 0 deletions website/docs/proto/commands/tools.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: tools
---

The `proto tools` command will list all tools that have been installed, along with their installed
versions, relevant timestamps, available aliases, and store location.

```shell
$ proto tools
go - Go
Store: ~/.proto/tools/go
Versions:
1.20.0 - installed 08/24/23, last used 09/18/23
1.20.2 - installed 01/01/70, last used 09/18/23, default version

node - Node.js
Store: ~/.proto/tools/node
Aliases:
~20 = stable
Versions:
18.0.0 - installed 09/03/23, last used 09/18/23, default version
18.14.0 - installed 09/04/23, last used 09/04/23
18.17.1 - installed 09/04/23, last used 09/04/23
19.0.0 - installed 09/03/23
20.0.0 - installed 09/03/23
20.6.0 - installed 09/04/23, last used 09/18/23
```

A list of tool IDs can be provided to filter the output list.

```shell
$ proto tools node npm
```

### Arguments

- `[id...]` - IDs of plugins.

### Options

- `--json` - Print the list in JSON format.
66 changes: 51 additions & 15 deletions website/docs/proto/config.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ proto supports pinning versions of tools on a per-project or per-directory basis
`.prototools` configuration file. This file takes precedence during [version detection](./detection)
and can be created/updated with [`proto local`](./commands/local).

This configuration simply maps tools to fully-qualified semantic versions for the current directory.
This configuration simply maps tools to versions for the current directory.

```toml title=".prototools"
node = "16.16.0"
Expand All @@ -26,9 +26,10 @@ rust = "1.68.0"

> The names of tools are the same used on the command line!
### Plugins
### `[plugins]`

[Plugins](./plugins) can also be configured on a per-project basis with the `[plugins]` section.
[Plugins](./plugins) can also be configured with the `[plugins]` section.
[Learn more about this syntax](./plugins#enabling-plugins).

```toml title=".prototools"
[plugins]
Expand All @@ -47,26 +48,61 @@ proto operates with sane defaults and accomplishes its goals very well. However,
user choice and customization, and as such, support a user configuration file located at
`~/.proto/config.toml`, which can be used to customize the behavior of proto.

Some of these settings (excluding plugins) can also be configured via environment variables.

```shell
PROTO_AUTO_INSTALL=true proto run node
```

### `auto-install`

When enabled, will automatically installing missing tools when [`proto run`](./commands/run) is run,
instead of erroring. Defaults to `false`.

```toml title="~/.proto/config.toml"
auto-install = true
```

These settings (excluding plugins) can also be configured via environment variables.
### `auto-clean`

```shell
PROTO_AUTO_INSTALL=true proto run node
When enabled, will automatically clean up the proto cache when [`proto use`](./commands/use) is run.
Defaults to `false`.

```toml title="~/.proto/config.toml"
auto-clean = true
```

### `node-intercept-globals`

When enabled, will intercept global package installs for node/npm/pnpm/yarn and suggest using
[`proto install-global`](./commands/install-global) instead. Defaults to `true`.

```toml title="~/.proto/config.toml"
node-intercept-globals = false
```

### `[http]`

Can be used to customize the HTTP client used by proto and warpgate, primarily for requesting files
to download, available versions, and more. The following settings are available:

- `allow-invalid-certs` - When enabled, will allow invalid certificates instead of failing. This is
an _escape hatch_ and should only be used if other settings have failed. Be sure you know what
you're doing!
- `proxies` - A list of proxy URLs to use for requests.
- `root-cert` - The path to a root certificate to use for requests. This is useful for overriding
the native certificate, or for using a self-signed certificate, especially when in a
corporate/internal environment. Supports `pem` and `der` files.

```toml title="~/.proto/config.toml"
[http]
root-cert = "/path/to/root/cert.pem"
```

### Settings
### `[plugins]`

- `auto-install` - When enabled, will automatically installing missing tools when
[`proto run`](./commands/run) is run, instead of erroring. Defaults to `false`.
- `auto-clean` - When enabled, will automatically clean up the proto cache when
[`proto use`](./commands/use) is run. Defaults to `false`.
- `node-intercept-globals` - When enabled, will intercept global package installs for npm/pnpm/yarn
and suggest using [`proto install-global`](./commands/install-global) instead. Defaults to `true`.
- `[plugins]` - A mapping of plugins available to the user. Refer to the [plugins](#plugins) section
above for more information.
A mapping of plugins available to the user, and not just a project/directory. Refer to the
[`[plugins]`](#plugins) section above for more information.

## GitHub Action

Expand Down
1 change: 1 addition & 0 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,7 @@ const sidebars = {
'proto/commands/remove-plugin',
'proto/commands/run',
'proto/commands/setup',
'proto/commands/tools',
'proto/commands/unalias',
'proto/commands/uninstall',
'proto/commands/uninstall-global',
Expand Down

0 comments on commit e942920

Please sign in to comment.