instavm 0.13.0 → 0.15.0

package/README.md

@@ -1,8 +1,8 @@
-# InstaVM JavaScript SDK
+# InstaVM JavaScript SDK + CLI
 
 ![Build Status](https://github.com/instavm/js/actions/workflows/ci.yml/badge.svg)
 
-Official JavaScript/TypeScript client for [InstaVM](https://instavm.io) — secure code execution in ephemeral microVMs with browser automation, networking controls, and platform APIs.
+Official JavaScript/TypeScript SDK and installed CLI for [InstaVM](https://instavm.io). Use it to manage VMs, snapshots, shares, volumes, desktops, account settings, and code execution from Node.js or your shell.
 
 ## Installation
 
@@ -12,24 +12,89 @@ npm install instavm
 
 **Requirements:** Node.js 18+, TypeScript 4.7+ (optional)
 
-## Quick Start
+## CLI
+
+The published package includes an `instavm` binary.
+
+```bash
+npx instavm --help
+pnpm exec instavm --help
+yarn exec instavm --help
+bunx instavm --help
+```
+
+If you want `instavm` directly on your PATH, install it globally:
+
+```bash
+npm install -g instavm
+instavm --help
+```
+
+The CLI stores defaults in `~/.instavm/config.json`, checks `INSTAVM_API_KEY` when no key is stored, and also respects `INSTAVM_BASE_URL` and `INSTAVM_SSH_HOST`.
+
+### Auth & Config
+
+```bash
+instavm auth set-key
+instavm auth status
+printf '%s' "$INSTAVM_API_KEY" | instavm auth set-key
+```
+
+### Common Commands
+
+```bash
+instavm whoami
+instavm ls
+instavm create --type computer-use --memory 4096
+instavm connect vm_123
+instavm snapshot ls
+instavm volume ls
+instavm volume files upload <volume_id> ./README.md --path docs/README.md
+instavm share create vm_123 3000 --public
+instavm share set-private <share_id>
+instavm ssh-key list
+instavm desktop viewer <session_id>
+instavm doc
+instavm billing
+```
+
+### Command Reference
+
+- `auth`: `set-key`, `status`, `logout`
+- `whoami`: show account details and SSH keys
+- `create`/`new`, `ls`/`list`, `rm`/`delete`, `clone`, `connect`: core VM workflows
+- `snapshot`: `ls`, `create`, `build`, `get`, `rm`
+- `desktop`: `status`, `start`, `stop`, `viewer`
+- `volume`: `ls`, `get`, `create`, `update`, `rm`, `checkpoint`, `files`
+- `share`: `create`, `set-public`, `set-private`, `revoke`
+- `ssh-key`: `list`, `add`, `remove`
+- `doc`/`docs`, `billing`: docs and billing links
+
+All leaf commands support `--json`. Share visibility updates use `share_id`, which matches the public API.
+
+## Library Quick Start
 
 ```typescript
 import { InstaVM } from 'instavm';
 
 const client = new InstaVM(process.env.INSTAVM_API_KEY || 'your_api_key');
 
-try {
-  const result = await client.execute("print('hello from instavm')");
-  console.log(result.stdout);
-} finally {
-  await client.dispose();
-}
+const [me, vms] = await Promise.all([
+  client.getCurrentUser(),
+  client.vms.list(),
+]);
+
+console.log(me.email);
+console.log(vms.length);
 ```
 
 ## Table of Contents
 
-- [Quick Start](#quick-start)
+- [CLI](#cli)
+  - [Auth & Config](#auth--config)
+  - [Common Commands](#common-commands)
+  - [Command Reference](#command-reference)
+- [Library Quick Start](#library-quick-start)
 - [Code Execution](#code-execution)
   - [Cloud Mode](#cloud-mode)
   - [Local Mode](#local-mode)
@@ -424,7 +489,13 @@ npm run build        # Build package
 
 ## Changelog
 
-Current package version: **0.13.0**
+Current package version: **0.15.0**
+
+### 0.15.0
+
+- Installed `instavm` CLI for `npm`, `pnpm`, `yarn`, `bun`, and global package installs
+- Stored CLI auth/config in `~/.instavm/config.json` with `INSTAVM_API_KEY` fallback
+- Added [`getCurrentUser()`](#library-quick-start) and `getSessionStatus(sessionId?)` helpers for identity and desktop workflows
 
 ### 0.13.0