Metadata-Version: 2.1
Name: helix256.io
Version: 0.1.0
Summary: helix, the Helix command line for orchestrators: rent pools of workers from a terminal
Keywords: helix,bittensor,orchestrator,cli
Project-URL: Homepage, https://helix256.io
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Distributed Computing
Description-Content-Type: text/markdown

# helix

`helix` is the command line of [Helix](https://helix256.io) for orchestrators (Bittensor subnet
105 miners). It does what the web app does: register your hotkey, browse the catalog of worker
pools, rent and pay for pools, list and inspect rentals, extend and cancel them. Its commands,
flags and look follow `btcli`, and it reads btcli's wallets and config.

It runs on macOS 11 or later and on Linux (any distribution), on x86-64 and arm64.

## Install

With Python, in a virtual environment (where you run btcli, for instance):

```sh
pip install helix256.io
helix --version
```

Or as a standalone tool, outside any environment:

```sh
pipx install helix256.io
# or
uv tool install helix256.io
```

Debian 12+ and Ubuntu 23.04+ refuse `pip install` into the system Python
(`externally-managed-environment`): use a virtual environment, `pipx` or `uv tool` instead.

Without Python:

```sh
curl -fsSL https://cdn.helix256.io/install.sh | sh
```

The script installs `helix` into `~/.local/bin`, without sudo, after checking its SHA-256.
`HELIX_VERSION=X.Y.Z` installs a given version, `HELIX_INSTALL_DIR=<dir>` another directory.
The archives are also at `https://cdn.helix256.io/cli/vX.Y.Z/`, with a `SHA256SUMS` file.

The package holds the compiled `helix` binary only: it installs no Python module, and Python
plays no part once it is installed.

**Name clash.** The Helix text editor is packaged on Arch Linux (`pacman -S helix`) with a binary
also called `helix` (other distributions name it `hx`). If you use it, put this CLI earlier on
your `PATH`, or install it under another name, such as `helix-cli`.

## Quick start

```sh
helix config set --wallet-name miner --hotkey default   # or rely on btcli's config
helix account register                                  # once per hotkey
helix pools list --available now
helix pools show --pool pool_abc123
helix account card add                                  # once: save a card on a Stripe page
helix rentals create --pool pool_abc123 --periods 3     # summary, [y/n], then the card is charged
helix rentals list
helix rentals show --rental rnt_abc123
```

## Commands

| Command | Aliases | What it does |
|---|---|---|
| `helix config set \| get \| clear` | `c`, `conf` | Write, show or clear `~/.helix/config.yml`. |
| `helix account register \| show` | `a` | Register your hotkey as an orchestrator (as a first sign-in on the web does), or show the account and its saved card. |
| `helix account card add \| show \| remove` | `a` | Save the card rentals are charged to (on a Stripe page), show it, or remove it. |
| `helix pools list \| show` | `p`, `pool` | Browse the public catalog: `--search`, `--kind`, `--region`, `--available`, `--cpu`, `--memory`, `--sort`, `--limit`, `--offset`; `show --pool`. |
| `helix rentals list \| show` | `r`, `rental` | Rentals covering now (`--all`: every rental); one rental with its workers (while active) and usage. |
| `helix rentals create \| pay \| extend \| cancel` | `r`, `rental` | Rent a pool, pay a reserved rental, extend a running one, cancel an unpaid one. |

Identifiers are flags, as in btcli: `--pool`, `--rental`, `--periods`. A missing one is asked
for; with `--no-prompt` it is an error. `helix <command> --help` shows every option and
examples.

### Paying

`rentals create` (unless `--no-pay`), `rentals extend` (unless `--no-pay`) and `rentals pay` pay
the rental with the card saved on Helix (`helix account card add`, or Manage on the web) once
you confirm, or on a Stripe Checkout page without one (or with `--checkout`). When the bank asks
for 3-D Secure, or for Checkout, the CLI prints the page, opens it when there is a browser, and
waits for the confirmation (`--timeout`, 35 minutes by default). A declined card shows Stripe's
reason and offers Checkout.

Ctrl-C stops waiting, not the rental: it stays reserved until its payment window closes, and
`helix rentals pay --rental <id>` resumes.

## Global options

| Option | Aliases | |
|---|---|---|
| `--wallet-name` | `--name`, `--wallet_name`, `--wallet.name` | Wallet name. |
| `--wallet-path`, `-p` | `--wallet_path`, `--wallet.path` | Wallets directory. |
| `--hotkey`, `-H` | `--wallet-hotkey`, `--wallet_hotkey`, `--wallet.hotkey` | Hotkey name in the wallet. |
| `--hotkey-file` | | A btcli hotkey file, instead of a wallet's. |
| `--network` | | `staging`, `local`, or an API URL. |
| `--no-prompt`, `-y` | `--yes`, `--no_prompt` | Confirm every prompt; fail on a missing value. |
| `--quiet` / `--verbose` | | Less, or more, on the console. |
| `--json-output` | `--json-out`, `--json` | The result as JSON on stdout, nothing else there. |

## Which hotkey signs

The first match wins:

1. `--hotkey-file <path>`;
2. `HELIX_HOTKEY_FILE`;
3. `HELIX_HOTKEY_SEED`: the hotkey's secret seed (`0x` and 64 hex digits), mnemonic or
   derivation, from the environment only (never a flag);
4. the wallet: each of its name, path and hotkey from the flags, else `~/.helix/config.yml`,
   else btcli's `~/.bittensor/config.yml`, else btcli's defaults: `~/.bittensor/wallets`,
   `default`, `default`.

Password-protected (encrypted) hotkey files are not supported yet: give the seed in
`HELIX_HOTKEY_SEED` instead. The catalog commands (`pools`) need no hotkey.

## Exit codes

`0` success, `1` error, `2` usage (a bad or missing flag), `3` authentication (unknown hotkey,
disabled orchestrator), `4` not found, `5` conflict (pool unavailable, rental not running...),
`6` card declined and Checkout not chosen (the rental stays reserved), `130` interrupted.
