# Install Pop CLI

> **Quick install (macOS/Linux with Homebrew)**
>
> ```bash
> brew install r0gue-io/pop-cli/pop
> ```
>
> Need Homebrew? Follow [Install Homebrew](#install-homebrew-if-not-installed).

## Other install options

**Using cargo-binstall** (cross-platform, downloads pre-built binaries when available):

```bash
# Install cargo-binstall if you don't have it
curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash

# Install pop-cli
cargo binstall pop-cli --locked
```

**Using Ubuntu PPA:**

```bash
sudo add-apt-repository ppa:r0gue-io/pop
sudo apt-get update
sudo apt-get install pop-cli
```

> If `add-apt-repository` is not found, install it with `sudo apt-get install software-properties-common`.

**Debian/Ubuntu** (using `.deb` package from GitHub Releases):

```bash
sudo dpkg -i pop-cli_*.deb
```

**Nix/NixOS:**

```bash
# Run directly without installing
nix run github:r0gue-io/pop-cli

# Or install to your profile
nix profile install github:r0gue-io/pop-cli
```

**Arch Linux** (using `pacman` with a `.pkg.tar.zst` from GitHub Releases):

```bash
sudo pacman -U pop-cli-*.pkg.tar.zst
```

## 1. Install Pop CLI

### 1.1 For macOS and Linux (Homebrew)

#### Install Homebrew (if not installed)

Run the official installer (more info [here](https://brew.sh)):

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Add Homebrew to your PATH (if the installer didn’t do it for you):

* macOS (Apple Silicon):

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$([ -x /opt/homebrew/bin/brew ] && /opt/homebrew/bin/brew shellenv)"
```

* Linux:

```bash
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$([ -x /home/linuxbrew/.linuxbrew/bin/brew ] && /home/linuxbrew/.linuxbrew/bin/brew shellenv)"
```

Verify:

```bash
brew --version
```

#### Install Pop CLI with Homebrew:

```bash
brew install r0gue-io/pop-cli/pop
```

### 1.2 Build from source (any OS)

Firstly, install Rust:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

And now build pop-cli from source and install it:

```bash
cargo install --force --locked pop-cli
```

## 2. Set up your environment

> **Recommended next step:** Run `pop install` to set up OS packages, Rust tooling, and optional frontend dependencies.

```bash
pop install
```

> **Warning:** `pop install` may download and run external scripts when dependencies are missing, including the official installers for Homebrew, rustup, nvm, and Bun.

### Install command flags

| Flag                   | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| `-y`, `--skip-confirm` | Skip confirmation prompts and install everything non-interactively. |
| `-f`, `--frontend`     | Install frontend dependencies (Node.js v20+ and Bun).               |

### JSON mode

Use global `--json` for structured automation output:

```bash
pop --json install --skip-confirm
pop --json completion --shell zsh --output ~/.zsh/completions/_pop
```

JSON mode notes:

* `pop --json install` requires `-y/--skip-confirm`.
* `pop --json completion` requires a shell via positional `SHELL` or `--shell`.

### Interactive prompts

By default, `pop install` prompts you before installing OS packages and frontend dependencies. Use `-y` to skip all prompts.

### Rust toolchain setup

`pop install` installs or updates rustup, then:

* Sets the default toolchain to `stable`
* Updates Rust
* Adds the `wasm32-unknown-unknown` target
* Installs components: `cargo`, `clippy`, `rust-analyzer`, `rust-src`, `rust-std`, `rustc`, `rustfmt`

> **Compatibility notes:** Pop CLI targets ink! v6 by default in the latest releases. If you need ink! v5 support, install version `0.10.0`:
>
> ```bash
> cargo install --locked pop-cli --version 0.10.0
> ```

### Installing frontend dependencies

If you plan to use frontend templates, you can install the required frontend dependencies:

```bash
pop install -y --frontend
```

This will install:

* Node.js (v20+) via `nvm` if your current `node --version` check fails or is too old
* Bun (required for certain frontend templates like [inkathon](https://github.com/scio-labs/inkathon))

If Bun installs successfully but is not on your PATH yet, Pop CLI checks the default location at `~/.bun/bin/bun`.

### Set up shell completion

Use `pop completion` to generate shell completion scripts for Bash, Zsh, Fish, PowerShell, or Elvish.

#### Usage

```bash
pop completion [SHELL] [--shell <SHELL>] [--output <PATH>]
```

#### Arguments and flags

| Argument/flag           | Description                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `SHELL`                 | Optional positional shell (`bash`, `zsh`, `fish`, `powershell`, `elvish`). Mutually exclusive with `--shell`. |
| `--shell <SHELL>`       | Shell to generate completions for (same values as `SHELL`).                                                   |
| `-o`, `--output <PATH>` | Write the completion script to a file instead of stdout.                                                      |

#### Behavior and defaults

* If you omit `--output`, Pop writes the completion script to stdout.
* If you pass `--output`, Pop writes the file and prints post-install steps for the selected shell.
* If you pass `--output` without a shell, Pop tries to detect the shell from `$SHELL`. If it detects one, it uses that shell and continues. If it cannot detect one and stdin is a TTY, it falls back to interactive setup. If stdin is not a TTY, it returns an error.
* In interactive setup, Pop asks you to choose a shell, suggests a default output path, and confirms before writing the file.

#### Default output paths (interactive)

| Shell        | Default path                                     |
| ------------ | ------------------------------------------------ |
| `bash`       | `~/.local/share/bash-completion/completions/pop` |
| `zsh`        | `~/.zsh/completions/_pop`                        |
| `fish`       | `~/.config/fish/completions/pop.fish`            |
| `powershell` | `~/.config/powershell/Completions/pop.ps1`       |
| `elvish`     | `~/.config/elvish/lib/pop.elv`                   |

#### Post-install steps by shell

| Shell        | Steps                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `bash`       | Source the file once, add `source <PATH>` to `~/.bashrc`, then restart your shell.                                                         |
| `zsh`        | Add the completion directory (the parent of the output file) to `fpath`, run `autoload -Uz compinit && compinit`, then restart your shell. |
| `fish`       | Restart your shell; Fish auto-loads completions from the standard completions directory.                                                   |
| `powershell` | Ensure your PowerShell profile loads the completion file, then restart your shell.                                                         |
| `elvish`     | Ensure your Elvish config loads the completion file, then restart your shell.                                                              |

#### Examples

```bash
pop completion zsh --output ~/.zsh/completions/_pop
```

```bash
pop completion bash > ~/.local/share/bash-completion/completions/pop
```

```bash
pop completion --shell fish --output ~/.config/fish/completions/pop.fish
```

#### Errors and constraints

* `--output` requires a shell if `$SHELL` is not set and stdin is not a TTY.
* The output path cannot be empty.
* Interactive setup requires a resolved home directory.

## 3. Advanced details

### OS packages and behavior

If your OS/distro is unsupported, `pop install` prints a warning and exits without installing OS packages or tooling.

| OS                      | Package manager | Packages installed                                                                                                                                 |
| ----------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS                   | Homebrew        | `homebrew`, `protobuf`, `openssl`, `cmake`, `rustup`                                                                                               |
| Arch (or compatible)    | `pacman`        | `curl`, `git`, `clang`, `make`, `protobuf`, `rustup`                                                                                               |
| Ubuntu (or compatible)  | `apt`           | `git`, `clang`, `curl`, `libssl-dev`, `protobuf-compiler`, `lsof`, `pkg-config`, `rustup`                                                          |
| Debian (or compatible)  | `apt`           | `git`, `clang`, `curl`, `libssl-dev`, `llvm`, `libudev-dev`, `make`, `protobuf-compiler`, `lsof`, `rustup`                                         |
| Red Hat (or compatible) | `yum`           | `gcc`, `gcc-c++`, `make`, `cmake`, `pkgconf`, `pkgconf-pkg-config`, `clang`, `curl`, `git`, `openssl-devel`, `protobuf-compiler`, `lsof`, `rustup` |

When you pass `--frontend`, `pop install` also installs `unzip` on Arch, Ubuntu, and Debian.

**Need help?**

Ask on [Polkadot Stack Exchange](https://polkadot.stackexchange.com/) (tag it [`pop`](https://substrate.stackexchange.com/tags/pop/info)) or drop by [our Telegram](https://t.me/onpopio). We're here to help!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.onpop.io/contracts/welcome/install-pop-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.