greevils

# greevils-cli

The participant's CLI. **Everything the participant does runs through this** — package,
submit, check status, deploy. The participant never touches the web. `package` and `deploy`
are fully local (the backend never sees plaintext or your `AGENT_KEY`); `submit` / `list` /
`status` talk to [greevils-api](../greevils-api/).

## Install
```bash
cd greevils-cli
python3 -m venv .venv && . .venv/bin/activate
pip install -e .        # installs a real `greevils` command on PATH (no alias needed)
```
The `greevils` command comes from the console-script entry point in
[pyproject.toml](pyproject.toml). Use `pipx install .` to install it globally instead.

Point it at the backend with `--api` or `GREEVILS_API` (default `http://localhost:8000`).

## The full workflow

### 1. Build your agent directory, then package it
Your agent is a **directory** that MUST contain `entry.py` (the fixed entrypoint, run as
`python entry.py` inside the TEE) and SHOULD contain `requirements.txt` (your pip deps). Lay out
the rest however you like. Your code trades by making plain HTTP calls to the harness at
`$GREEVILS_AGENT_URL` (`http://127.0.0.1:8081`) — no SDK to import. See
[example-agent/](example-agent/).
```bash
greevils package ./my-agent -o agent-bundle.enc   # prints AGENT_KEY=... and AGENT_SHA256=...
```
`AGENT_KEY` is symmetric: it encrypts now and decrypts inside the TEE at deploy. **Save it
safely** — without it you can't deploy or redeploy, and it's never recoverable from the backend
(the backend only ever holds the ciphertext). `AGENT_SHA256` is the agent identity the harness
publishes at `GET /agent`, so you can confirm exactly which code is running.

### 2. Submit the bundle (names your agent, stores it, triggers the build)
```bash
greevils submit agent-bundle.enc --name my-cool-agent
# submitted: id=a1b2c3d4  name=my-cool-agent  status=QUEUED
# token:     <secret>   (saved to ~/.greevils/tokens.json — keep a copy)
```
Agent **names are unique** — if the name is already taken the submit is rejected and the CLI
prints the reason (`submit failed: submission name '…' is already taken -- pick another`); just
rerun with a different `--name`.

Submit returns a **submission token** — your write capability for that submission (it gates
reporting the deploy IP). The CLI saves it to `~/.greevils/tokens.json` and reuses it
automatically; the server keeps only its hash, so it can't be recovered if you lose it.

**Pip packages.** Put a `requirements.txt` **inside your agent directory** (so it's encrypted in
the bundle — the organizer never sees it). The agent process pip-installs it at runtime inside
the TEE, before `entry.py` runs. Because it's installed from PyPI at runtime, it is **not** part
of digest **D** (only the requirements.txt text is, via the agent hash); pin versions/hashes if
you need reproducible installs, and prefer wheels (the slim base has no compiler).

### 3. Watch the build
```bash
greevils list                 # all submissions; find yours by name
greevils status a1b2c3d4      # QUEUED -> BUILDING_IMAGE -> PUBLISHING_IMAGE -> PUBLISHED
greevils status a1b2c3d4 --log    # include the build log (handy on FAILED)
```
When `PUBLISHED`, `status` shows the `image_ref` and `image_digest` (D).

### 4. Deploy with the published image
```bash
greevils deploy a1b2c3d4 \
  --agent-key "$AGENT_KEY" \
  --master-account 0xYourEOA \
  --env-file .env \
  --project your-gcp-project --zone us-central1-a
```
`deploy` resolves `image_ref`/`digest` from the submission id, then launches a Confidential
Space TDX VM running that exact image, passing `AGENT_KEY` + `MASTER_ACCOUNT` as
`tee-env-*`. It prints the VM's external IP (give it + the digest to the organizer/verifier).
`AGENT_KEY` / `MASTER_ACCOUNT` also read from `$AGENT_KEY` / `$MASTER_ACCOUNT`.

**Your own env vars / API keys (`--env-file`).** Put any env vars your agent needs in a
`.env`-style file (`KEY=VALUE` per line; `#` comments and a leading `export ` are fine) and
pass `--env-file .env`. Your agent then reads them with `os.environ["OPENAI_API_KEY"]` etc.,
as usual. The CLI packs the whole file into one base64(JSON) blob and passes it as a single
`tee-env-AGENT_ENV`, which the TEE harness unpacks into the environment before your agent
loads. Because deploy runs **on your own infra**, these names and values live only in your own
VM's metadata — the organizer never sees them, and they are **not** part of the attested
digest. A handful of names are reserved and silently ignored if present in your file:
`AGENT_KEY`, `MASTER_ACCOUNT`, `AGENT_ENV`, `CS_TOKEN_BACKEND`, `CS_TOKEN_AUDIENCE`.

When you deploy by `<id>`, the CLI also **reports the VM's public IP back to the API**, which
marks the submission `DEPLOYED` (visible in `list`/`status`). The report is authenticated with
your **submission token** (saved on `submit`); the CLI finds it automatically, or pass
`--token` / set `$GREEVILS_TOKEN`. If the report fails, the deploy still succeeds and the CLI
prints a `curl` you can run to report the IP yourself.

> Deploy itself bypasses the API by design (`--id` is only used to look up the public image
> ref + digest, and to report the IP afterward). You can skip the API entirely with
> `greevils deploy --image-ref ... --digest ...` (no IP is reported in that case).

### 5. Claim your Hyperliquid account on-chain (subnet miners)

To be scored by the subnet validator, register your neuron on the subnet, then publish a
one-time on-chain **ownership commitment** that proves you control a Hyperliquid account
(either a greevil **agent** account or a **normal** trading account):

Sign the canonical message in the Greevils web UI with your Hyperliquid account, then pass
the resulting address + signature to the CLI to commit it (the CLI never sees your key):

```bash
greevils commit --netuid 1 --coldkey my-wallet --hotkey my-hotkey \
  --hl-address 0xACCT --signature 0xSIG
```

The on-chain commitment is the compact blob `base64(hl_address(20B) ‖ signatu