Skip to content

Latest commit

 

History

History
309 lines (231 loc) · 7.6 KB

setup.mdx

File metadata and controls

309 lines (231 loc) · 7.6 KB
toc_max_heading_level
2

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, as well as a GitHub Action for CI/CD installs. If you want to run it on another platform, you can build the CLI from source.

Download the latest release from our GitHub repository and follow the instructions for your platform below:

### Homebrew 
If you use [Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux),
you can install the Oasis CLI with:

#### Installation

```shell
brew install oasis
```

#### Verify

```shell
oasis --version
```

### Manual

#### 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
   ```
### Homebrew (Recommended) 
The recommended way to install the Oasis CLI on macOS is via
[Homebrew](https://brew.sh/).

#### Installation

```shell
brew install oasis
```

#### Verify

```shell
oasis --version
```

### Manual

#### 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
   ```
To setup Oasis CLI for GitHub CI/CD workflows, we recommend using our [setup-cli-action](https://github.com/oasisprotocol/setup-cli-action) GitHub Action. 
#### Setup

Simply add a Setup Oasis CLI step to your workflow:

```yaml
steps:
- name: Setup Oasis CLI
  uses: oasisprotocol/setup-cli-action
```

#### Verify

```yaml
- name: Check Oasis CLI version
  run: oasis --version
```

#### Configuration

Optionally you can use the version parameter to install a different version of the CLI.

```yaml
steps:
- name: Setup Oasis CLI
  uses: oasisprotocol/setup-cli-action
  with:
    version: '0.14.3'
```

Update

If you installed Oasis CLI manually, the application includes a built-in oasis update command which upgrades software to the latest version.

This command will check for a newer version on GitHub, show you the release notes, and ask for confirmation before downloading and replacing the current binary.

Shell Completion

The Oasis CLI supports shell completion for Bash, Zsh, Fish, and PowerShell. Completions allow you to press Tab to auto-complete commands, subcommands, and flags.

#### Temporary (current session) 
```shell
source <(oasis completion bash)
```

#### Permanent

**Linux:**
```shell
oasis completion bash > /etc/bash_completion.d/oasis
```

**macOS (Homebrew):**
```shell
oasis completion bash > $(brew --prefix)/etc/bash_completion.d/oasis
```
#### Temporary (current session) 
```shell
source <(oasis completion zsh)
```

#### Permanent

First, ensure completion is enabled in your `~/.zshrc`:
```shell
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

Then install the completion:
```shell
oasis completion zsh > "${fpath[1]}/_oasis"
```

Start a new shell for the changes to take effect.
#### Temporary (current session) 
```shell
oasis completion fish | source
```

#### Permanent

```shell
oasis completion fish > ~/.config/fish/completions/oasis.fish
```
#### Temporary (current session) 
```powershell
oasis completion powershell | Out-String | Invoke-Expression
```

#### Permanent

Add the following to your PowerShell profile:
```powershell
oasis completion powershell | Out-String | Invoke-Expression
```

To find your profile path, run `echo $PROFILE` in PowerShell.

Configuration

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.

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

code

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.