npm package: @suronai/cli
Description: CLI for Suron — suron login, init, whoami, recover
Latest version: 0.1.36

# @suronai/cli

CLI for [Suron](https://suronai.com) — encrypt your `.env`, register your app, and manage secret delivery gated by Telegram approval.

## Install

```bash
npm install -g @suronai/cli
```

Requires Node.js 18+.

---

## Quick start

```bash
suron login       # point the CLI at your Suron deployment
cd my-project
suron init        # encrypt .env, register app, patch entry point
```

After `suron init`, both `.env` and `.suron.json` are safe to commit.

---

## Commands

### `suron login`

Saves your Convex deployment URL to `~/.suron-config`. Run this once per machine.

```bash
suron login
```

You can also set it via environment variable instead:

```bash
export SURON_API_URL=https://your-deployment.convex.site
```

---

### `suron init`

Run inside your project directory. Does the full setup in one command:

1. Encrypts `.env` in-place with [dotenvx](https://dotenvx.com)
2. Registers your app with Suron (uploads the encrypted private key)
3. Installs `@suronai/sdk` into your project
4. Writes `.suron.json` with your app name and ID
5. Deletes `.env.keys`
6. Detects `dotenv` in your entry point and offers to replace it with `@suronai/sdk`

```bash
cd my-project
suron init

# set a custom app name without the interactive prompt
suron init --name my-app
```

**Entry point patching**

If `index.js` (or `src/index.js`) contains a `dotenv` bootstrap, `suron init` shows you exactly what will change and asks before touching anything:

```
▶  Found dotenv in index.js

  Will replace:
    - import { config } from 'dotenv'
    - config()
  With:
    + import { config } from '@suronai/sdk'
    + await config()

  Replace? [Y/n] ›
```

If dotenv isn't found, the snippet is printed for you to add manually.

**Files after `suron init`**

| File | Commit? | Notes |
|---|---|---|
| `.env` | ✅ yes | encrypted by dotenvx, no plaintext secrets |
| `.suron.json` | ✅ yes | app name, id, api_url — no secrets |
| `.env.keys` | ⛔ no | keep safe, add to `.gitignore` |
| `~/.suron-config` | ⛔ no | machine-local CLI config |

---

### `suron whoami`

Prints the configured Suron API URL.

```bash
suron whoami
```

---

### `suron rotate`

Re-encrypts `.env` with a new private key, sends the updated key to Suron, and deletes `.env.keys`. Use this for routine key rotation or if a key may have been exposed.

```bash
suron rotate
```

---

## How it works

```
suron init
  └─ dotenvx encrypt .env          # encrypts secrets in-place
  └─ POST /cli/register-app        # sends encrypted private key to Convex
  └─ writes .suron.json            # stores app_id locally
  └─ deletes .env.keys             # private key lives in Convex only

app boot (via @suronai/sdk)
  └─ POST /request-access          # sends boot request, triggers Telegram message
  └─ GET  /status (polling)        # waits for Approve / Deny tap
  └─ POST /fetch-key               # retrieves private key (single-use)
  └─ dotenvx.parse(.env, key)      # decrypts secrets into process.env
```

---

## Related

- [`@suronai/sdk`](https://www.npmjs.com/package/@suronai/sdk) — the runtime SDK your app imports