diff --git a/.markdownlint.yml b/.markdownlint.yml index f993a52d..a409c4d8 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -27,3 +27,12 @@ link-fragments: false # Do not always require language specifiers with fenced code blocks since they # are not part of the Markdown spec. fenced-code-language: false + +# Allow inline HTML for MDX tab components. +no-inline-html: + allowed_elements: + - Tabs + - TabItem + +# MDX files often start with imports, so disable first-line heading rule. +first-line-heading: false diff --git a/Makefile b/Makefile index 1c157baa..a902381a 100644 --- a/Makefile +++ b/Makefile @@ -52,7 +52,7 @@ lint-git: lint-docs: @$(PRINT) "$(CYAN)*** Running markdownlint-cli...$(OFF)\n" - @npx --yes markdownlint-cli '**/*.md' + @npx --yes markdownlint-cli '**/*.md?(x)' lint-go-mod-tidy: @$(PRINT) "$(CYAN)*** Checking go mod tidy...$(OFF)\n" diff --git a/docs/README.md b/docs/README.md index 9fef43d1..b19b40e8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,8 +6,10 @@ description: Powerful CLI for managing Oasis networks, nodes, tokens and dApps # Oasis Command Line Interface Oasis command-line interface (CLI) is a powerful all-in-one tool for -interacting with the Oasis Network. You can download the latest release -binaries from the [GitHub repository]. +interacting with the Oasis Network. +Head to the **[installation instructions]** to download and install it! + +[installation instructions]: setup.mdx It boasts a number of handy features: @@ -19,8 +21,8 @@ It boasts a number of handy features: - connecting to remote (via TCP/IP) or local (Unix socket) Oasis node instance - Powerful wallet features: - - standard token operations (transfers, allowances, deposits, withdrawals and - balance queries) + - standard token operations (transfers, allowances, deposits, withdrawals + and balance queries) - file-based wallet with password protection - full Ledger hardware wallet support - address book @@ -32,7 +34,7 @@ It boasts a number of handy features: schemes - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths - Node operator features: - - Oasis node inspection and healthchecks + - Oasis node inspection and health-checks - network governance transactions - staking reward schedule transactions - Developer features: @@ -43,5 +45,4 @@ It boasts a number of handy features: calls - debugging tools for deployed Wasm contracts - inspection of blocks, transactions, results and events - -[GitHub repository]: https://github.com/oasisprotocol/cli/releases + \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md deleted file mode 100644 index 76802ceb..00000000 --- a/docs/setup.md +++ /dev/null @@ -1,78 +0,0 @@ -# Setup - -## Download and Run - -Download the latest release from our [GitHub repository][cli-releases] and -extract it to your favorite application folder. - -:::info - -Oasis is currently providing official amd64 for Linux and ARM builds for MacOS. -If you want to run it on another platform, you will have to -[build it from source][cli-source]. - -::: - -:::info - -We suggest that you update your system path to include a directory containing -the `oasis` binary or create a symbolic link to `oasis` in your -system path, so you can access it globally. - -::: - -Run the Oasis CLI by typing `oasis`. - -![code](../examples/setup/first-run.out) - -When running the Oasis CLI for the first time, it will generate a configuration -file and populate it with the current Mainnet and Testnet networks. It will also -configure all [ParaTimes supported by the Oasis Foundation][paratimes]. - -## Configuration - -The configuration folder of Oasis CLI is located: - -- on Windows: - - `%USERPROFILE%\AppData\Local\oasis\` -- on macOS: - - `/Users/$USER/Library/Application Support/oasis/` -- on Linux: - - `$HOME/.config/oasis/` - -There, you will find `cli.toml` which contains the configuration of the -networks, ParaTimes and your wallet. Additionally, each file-based account in -your wallet will have a separate, password-encrypted JSON file in the same -folder named after the name of the account with the `.wallet` extension. - -## Multiple Profiles - -You can utilize multiple profiles of your Oasis CLI. To create a new profile, -move your existing configuration folder to another place, for example: - -```shell -mv $HOME/.config/oasis $HOME/.config/oasis_dev -``` - -Then, invoke `oasis` with arbitrary command to set up a fresh configuration -folder under `~/.config/oasis`. For example: - -![code shell](../examples/setup/wallet-list.in) - -![code](../examples/setup/wallet-list.out) - -Now you can switch between the `oasis_dev` and the new profile by passing -`--config` parameter pointing to `cli.toml` in the desired configuration folder. - -![code shell](../examples/setup/wallet-list-config.in.static) - -![code](../examples/setup/wallet-list-config.out.static) - -## Back Up Your Wallet - -To back up your complete Oasis CLI configuration including your wallet, archive -the configuration folder containing `cli.toml` and `.wallet` files. - -[cli-releases]: https://github.com/oasisprotocol/cli/releases -[cli-source]: https://github.com/oasisprotocol/cli -[paratimes]: https://github.com/oasisprotocol/docs/blob/main/docs/build/tools/other-paratimes/README.mdx diff --git a/docs/setup.mdx b/docs/setup.mdx new file mode 100644 index 00000000..461234ca --- /dev/null +++ b/docs/setup.mdx @@ -0,0 +1,140 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Setup + +## Download and Run + +The Oasis team provides CLI binaries for Linux, +macOS and Windows operating systems. +If you want to run it on another platform, +you can [build the CLI from source][cli-source]. + +Download the latest release from our [GitHub repository][cli-releases] and +follow the instructions for **your platform** below: + + + + #### Prerequisites + + - amd64 or arm64 Linux. + - Ensure `~/.local/bin` is on your `PATH`: + ```shell + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc + source ~/.bashrc + mkdir -p ~/.local/bin + ``` + + #### Installation + + 1. Download the latest **Linux** archive (e.g. `oasis_cli_X.Y.Z_linux_amd64.tar.gz`). + 2. Extract it: + ```shell + cd ~/Downloads + tar -xzf oasis_cli_X.Y.Z_linux_amd64.tar.gz # adjust version and architecture + ``` + 3. Move the binary to your path: + ```shell + mv oasis ~/.local/bin/ + ``` + 4. Verify: + ```shell + oasis --version + ``` + + + + #### Prerequisites + + - macOS (Apple Silicon & Intel). + - Ensure `~/.local/bin` is on your `PATH` (add it in `~/.zshrc` or `~/.bashrc`): + ```shell + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + mkdir -p ~/.local/bin + ``` + + #### Installation + + 1. Download the latest **macOS** archive (e.g. `oasis_cli_X.Y.Z_darwin_all.tar.gz`) from the releases page. + 2. Extract it: + ```shell + cd ~/Downloads + tar -xzf oasis_cli_X.Y.Z_darwin_all.tar.gz # adjust version + ``` + 3. Move the binary to your path: + ```shell + mv oasis ~/.local/bin/ + ``` + 4. Bypass Gatekeeper (first run only): + ```shell + xattr -d com.apple.quarantine ~/.local/bin/oasis + ``` + If a dialog appears, open **System Settings → Privacy & Security** and click **Open Anyway**. + 5. Verify: + ```shell + oasis --version + ``` + + + + #### Prerequisites + + - Windows 10/11 (x86-64). + - Decide on a folder already in your `PATH` (e.g. `%USERPROFILE%\bin`) or add one. + + #### Installation + + 1. Download the latest **Windows** ZIP file (e.g. `oasis_cli_X.Y.Z_windows_amd64.zip`). + 2. Extract it (double-click or `tar -xf` in PowerShell). + 3. Copy `oasis.exe` to a directory on your `PATH`, for example: + ```powershell + New-Item -ItemType Directory -Force "$env:USERPROFILE\bin" + Copy-Item .\oasis.exe "$env:USERPROFILE\bin\" + ``` + If that folder isn’t on the `PATH`, add it via **System Properties → Environment Variables**. + 4. Verify: + ```powershell + oasis --version + ``` + + + +When running the Oasis CLI for the first time, it will generate a configuration +file and populate it with the current Mainnet and Testnet networks. It will also +configure all [ParaTimes supported by the Oasis Foundation][paratimes]. + +## Configuration + +The configuration folder of Oasis CLI is located: + +- on Linux: + - `$HOME/.config/oasis/` +- on macOS: + - `/Users/$USER/Library/Application Support/oasis/` +- on Windows: + - `%USERPROFILE%\AppData\Local\oasis\` + +There, you will find `cli.toml` which contains the configuration of the +networks, ParaTimes and your wallet. Additionally, each file-based account in +your wallet will have a separate, password-encrypted JSON file in the same +folder named after the name of the account with the `.wallet` extension. + +## Multiple Profiles + +You can utilize multiple profiles of your Oasis CLI by +passing the `--config` parameter +with a location of a desired `cli.toml`: + +![code shell](../examples/setup/wallet-list-config.in.static) + +![code](../examples/setup/wallet-list-config.out.static) + +## Back Up Your Wallet + +To back up your complete Oasis CLI configuration including your wallet, archive +the configuration folder containing `cli.toml` and `.wallet` files. + +[cli-releases]: https://github.com/oasisprotocol/cli/releases +[cli-source]: https://github.com/oasisprotocol/cli +[paratimes]: https://github.com/oasisprotocol/docs/blob/main/docs/build/tools/other-paratimes/README.mdx