instavm 0.13.0 → 0.16.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,126 @@ 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 ls -a
+instavm create --type computer-use --memory 4096
+instavm connect vm_123
+instavm deploy
+instavm deploy --plan
+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
+```
+
+`instavm ls` shows active VMs only. Use `-a` or `--all` to include terminated VM records.
+
+### Cookbooks
+
+`instavm cookbook` pulls curated starter apps from the public [`instavm/cookbooks`](https://github.com/instavm/cookbooks) catalog, creates a VM, starts the service, creates the share, and returns the public URL.
+
+```bash
+instavm cookbook list
+instavm cookbook info neon-city-webgl
+instavm cookbook deploy neon-city-webgl
+instavm cookbook deploy hello-fastapi
+```
+
+The CLI syncs the cookbook repo into `~/.instavm/cookbooks/`, checks for `git`, `ssh`, `scp`, and `tar`, prompts for any required secrets, and auto-registers a local public SSH key if your account does not already have one.
+
+### Deploy
+
+`instavm deploy` tries to deploy the app in the current directory without asking you to create an `instavm.yaml` first. It detects a simple Node.js or Python web app, creates a VM, uploads the project, starts the service, and gives you a share URL.
+
+```bash
+instavm deploy
+instavm deploy --plan
+instavm deploy ./path/to/app
+```
+
+`--plan` shows the detected runtime, install command, start command, port, and secrets without creating a VM.
+
+`instavm deploy` is experimental right now. The zero-config path is working best for straightforward Node.js and Python apps. Some runtimes and projects still need follow-up fixes or backend support.
+
+### Command Reference
+
+- `auth`: `set-key`, `status`, `logout`
+- `whoami`: show account details and SSH keys
+- `ls`/`list`: show active VMs by default; use `-a` or `--all` for all VM records
+- `cookbook`: `list`, `info`, `deploy` for curated starter apps from `instavm/cookbooks`
+- `deploy`: experimental zero-config deploy for the current app directory
+- `create`/`new`, `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)
+  - [Cookbooks](#cookbooks)
+  - [Deploy](#deploy)
+  - [Command Reference](#command-reference)
+- [Library Quick Start](#library-quick-start)
 - [Code Execution](#code-execution)
   - [Cloud Mode](#cloud-mode)
   - [Local Mode](#local-mode)
@@ -424,7 +526,23 @@ npm run build        # Build package
 
 ## Changelog
 
-Current package version: **0.13.0**
+Current package version: **0.16.0**
+
+### 0.16.0
+
+- Expanded CLI docs for `instavm cookbook`
+- Added experimental `instavm deploy` for zero-config app deploys from the current directory
+
+### 0.15.1
+
+- `ls` now matches the SSH gateway: active VMs by default, `-a` or `--all` for all VM records
+- `whoami` now uses the live `/v1/users/me` endpoint
+
+### 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