diff --git a/docs/cli-reference/dfx/dfx.mdx b/docs/cli-reference/dfx/dfx.mdx index a68c00f..c7cb1e4 100644 --- a/docs/cli-reference/dfx/dfx.mdx +++ b/docs/cli-reference/dfx/dfx.mdx @@ -1,82 +1,67 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# dfx +# Determining `dfx` version +When invoked as `dfx`, `dfxvm` determines which version of `dfx` to use for execution by checking these criteria in order: -When invoked as `dfx`, `dfxvm` determines which version of dfx to use -and dispatches execution to it. +1. `+` parameter from command line. +2. `DFX_VERSION` environment variable. +3. `dfx` setting in the current project's `dfx.json`. +4. `default_version` in `$HOME/.config/dfx/version-manager.json`. -## dfx version determination +#### 1. Command line -`dfxvm` determines which version of dfx to use by checking these criteria -in order: - -1. `+` parameter from command line -2. `DFX_VERSION` environment variable -3. `dfx` in the current project's `dfx.json` -4. `default_version` in `$HOME/.config/dfx/version-manager.json` - -### Command Line - -You can specify the version of dfx to use on the command line by passing -`+` as the first parameter. For example, the following will deploy -using dfx 0.15.0: +You can specify the version of `dfx` on the command line by passing `+` as the first parameter. For example, the following will deploy using `dfx v0.26.0`: ```bash -dfx +0.15.0 deploy +dfx +0.26.0 deploy ``` -### DFX_VERSION environment variable +#### 2. `DFX_VERSION` environment variable -You can specify the version of dfx to use by setting the `DFX_VERSION` -environment variable. For example, the following will start the replica using -dfx 0.15.0: +You can specify the version of `dfx` by setting the `DFX_VERSION` environment variable. For example, the following will start the local developer environment using `dfx v0.26.0`: ```bash -DFX_VERSION=0.15.0 dfx start --clean --background +DFX_VERSION=0.26.0 dfx start --clean --background ``` -### dfx field in the current project's dfx.json +#### 3. `dfx` field in the current project's `dfx.json` -If running dfxvm as dfx in a dfx project, and the project's dfx.json contains a -top-level field "dfx", then dfxvm will use the version specified in that field. +A project's `dfx.json` file can contain a top-level field "dfx". If specified, then `dfxvm` will use that version. -Like dfx, dfxvm looks for dfx.json in the current directory and then in -parent directories until it finds one or reaches the root directory. +Like `dfx`, `dfxvm` looks for `dfx.json` in the current directory and then in parent directories until it finds one or reaches the root directory. For example: ```json { - "dfx": "0.14.4", + "dfx": "0.26.1", "canisters": { } } ``` -If the above dfx.json were in the current directory or any parent directory, -then any dfx command would use dfx 0.14.4. +If the above `dfx.json` were in the current directory or any parent directory, then any `dfx` command would use `dfx v0.26.1`. -### default_version in $HOME/.config/dfx/version-manager.json +#### 4. `default_version` in `$HOME/.config/dfx/version-manager.json` -If none of the above criteria are met, then dfxvm will use the version specified -in `$HOME/.config/dfx/version-manager.json`. For example: +If none of the above criteria are met, then `dfxvm` will use the version specified in `$HOME/.config/dfx/version-manager.json`. For example: ```json { - "default_version": "0.15.0" + "default_version": "0.26.0" } ``` To configure the default dfx version, use the `dfxvm default` command: ```bash -dfxvm default 0.15.1 +dfxvm default 0.26.1 ``` -## Environment Variables +## Environment variables -When proxying to dfx, dfxvm alters the environment in two ways: -- Sets `DFX_VERSION` to the version of dfx being used. -- Prepends the bin directory for the dfx version to `PATH`. +When proxying to `dfx`, `dfxvm` alters the environment in two ways: +- Sets `DFX_VERSION` to the version of `dfx` being used. +- Prepends the `bin` directory for the `dfx` version to `PATH`. diff --git a/docs/cli-reference/dfxvm-init/dfxvm-init.mdx b/docs/cli-reference/dfxvm-init/dfxvm-init.mdx index 3b0b276..5a5e1ea 100644 --- a/docs/cli-reference/dfxvm-init/dfxvm-init.mdx +++ b/docs/cli-reference/dfxvm-init/dfxvm-init.mdx @@ -6,10 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; When invoked as `dfxvm-init`, `dfxvm` performs one-time installation tasks. -By default, installs the latest version of dfx, and gives you an opportunity -to customize the installation. - -## Usage +By default, installs the latest version of dfx, and gives you an opportunity to customize the installation. ```bash dfxvm-init [--dfx-version ] [--yes] @@ -25,19 +22,17 @@ dfxvm-init [--dfx-version ] [--yes] ## Examples -Install dfxvm and the latest version of dfx, with an opportunity -to customize the installation - ```bash dfxvm-init ``` -Install dfxvm and dfx 0.14.4, with an opportunity to customize the installation +Install `dfxvm` and `dfx 0.14.4`, with an opportunity to customize the installation: + ```bash dfxvm-init --dfx-version 0.14.4 ``` -Install dfxvm and the latest version of dfx without prompting for confirmation +Install `dfxvm` and the latest version of `dfx` without prompting for confirmation: ```bash dfxvm-init --yes diff --git a/docs/cli-reference/dfxvm/dfxvm-default.mdx b/docs/cli-reference/dfxvm/dfxvm-default.mdx index d8bee78..1e2a52a 100644 --- a/docs/cli-reference/dfxvm/dfxvm-default.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-default.mdx @@ -1,19 +1,22 @@ +import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; + # dfxvm default -Sets or displays the dfx version to use by default. + + +Sets or displays the `dfx` version that should be used by default. -When setting the default version, installs the specified version -if it is not already installed. +When setting the default version, `dfxvm default` installs the specified version if it is not already installed. ## Usage -Set the dfx version to use by default: +Set the `dfx` version to be used by default: ```bash dfxvm default ``` -Display the default dfx version: +Display the currently configured default `dfx` version: ```bash dfxvm default diff --git a/docs/cli-reference/dfxvm/dfxvm-install.mdx b/docs/cli-reference/dfxvm/dfxvm-install.mdx index e43cbb4..2aea9a3 100644 --- a/docs/cli-reference/dfxvm/dfxvm-install.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-install.mdx @@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Installs a version of dfx. - -## Usage +Installs a version of `dfx`. Can be used for official release versions and beta releases. ```bash dfxvm install diff --git a/docs/cli-reference/dfxvm/dfxvm-list.mdx b/docs/cli-reference/dfxvm/dfxvm-list.mdx index de46c2b..d52a3fa 100644 --- a/docs/cli-reference/dfxvm/dfxvm-list.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-list.mdx @@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -List installed or available versions of dfx. - -## Usage +List the currently installed or available versions of `dfx`. ```bash dfxvm list [OPTIONS] diff --git a/docs/cli-reference/dfxvm/dfxvm-self-uninstall.mdx b/docs/cli-reference/dfxvm/dfxvm-self-uninstall.mdx index 8616f00..71d1127 100644 --- a/docs/cli-reference/dfxvm/dfxvm-self-uninstall.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-self-uninstall.mdx @@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Uninstalls dfxvm and all versions of dfx. - -## Usage +Uninstalls `dfxvm` and all versions of `dfx` with the opportunity to confirm or cancel. ```bash dfxvm self uninstall [--yes] @@ -20,8 +18,6 @@ dfxvm self uninstall [--yes] ## Examples -Uninstall dfxvm and all versions of dfx, with an opportunity to confirm or cancel. - ```bash dfxvm self uninstall ``` diff --git a/docs/cli-reference/dfxvm/dfxvm-self-update.mdx b/docs/cli-reference/dfxvm/dfxvm-self-update.mdx index 162f664..f2dabdf 100644 --- a/docs/cli-reference/dfxvm/dfxvm-self-update.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-self-update.mdx @@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Updates to the newest version of dfxvm. - -## Usage +Updates to the newest version of `dfxvm`. Does not update to the latest version of `dfx`. ```bash dfxvm self update diff --git a/docs/cli-reference/dfxvm/dfxvm-uninstall.mdx b/docs/cli-reference/dfxvm/dfxvm-uninstall.mdx index 82e1657..67cd9a3 100644 --- a/docs/cli-reference/dfxvm/dfxvm-uninstall.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-uninstall.mdx @@ -4,17 +4,13 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Uninstalls a version of dfx. - -## Usage +Uninstalls a specific version of `dfx`. Does not uninstall `dfxvm` itself. ```bash dfxvm uninstall ``` -## Examples - -Uninstall a beta that you don't want anymore: +## Example ```bash dfxvm uninstall 0.15.1-beta.0 diff --git a/docs/cli-reference/dfxvm/dfxvm-update.mdx b/docs/cli-reference/dfxvm/dfxvm-update.mdx index 2c53cf2..2ef6db1 100644 --- a/docs/cli-reference/dfxvm/dfxvm-update.mdx +++ b/docs/cli-reference/dfxvm/dfxvm-update.mdx @@ -4,10 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Looks up the latest dfx version, installs it if not already installed, and -sets it as the default version. - -## Usage +Looks up the latest `dfx` version, installs it if not already installed, then sets it as the default version. ```bash dfxvm update diff --git a/docs/cli-reference/dfxvm/dfxvm.mdx b/docs/cli-reference/dfxvm/dfxvm.mdx index b860c23..2f1566a 100644 --- a/docs/cli-reference/dfxvm/dfxvm.mdx +++ b/docs/cli-reference/dfxvm/dfxvm.mdx @@ -4,4 +4,44 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -When invoked as `dfxvm`, manages dfx versions or itself. +`dfxvm` is the version manager for the command-line tool `dfx`. + +When invoked as `dfxvm`, manages `dfx` versions or itself. + +To set the default `dfx` version, use the `dfxvm default` command: + +``` +dfxvm default 0.25.1 +``` + +Or, to set the `dfx` version for a single command: + +``` +dfx +0.25.1 --version +``` + +The `dfx` version can be set manually in a project's `dfx.json` file: + +```json +{ + "dfx": "0.25.0" +} +``` + +## Subcommands + +Available subcommands are: + +- `dfxvm default` + +- `dfxvm install` + +- `dfxvm list` + +- `dfxvm self uninstall` + +- `dfxvm self update` + +- `dfxvm uninstall` + +- `dfxvm update` diff --git a/docs/cli-reference/index.mdz b/docs/cli-reference/index.md similarity index 88% rename from docs/cli-reference/index.mdz rename to docs/cli-reference/index.md index 313a840..b335a6d 100644 --- a/docs/cli-reference/index.mdz +++ b/docs/cli-reference/index.md @@ -1,9 +1,5 @@ -import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; - # Command-line reference - - The dfxvm binary is a chimera, changing its behavior based on the name of the binary.