## CLI `easybits` is EasyBits from your terminal: sandboxes, hosting, domains, databases, agents and files without writing a single `curl`. It is built for people **and for coding agents**: every command takes `--json` and the exit codes are stable. ### For your coding agent Install the EasyBits skills in your agent (Claude Code, Codex, Cursor…). They include `easybits-cli`, which teaches it this CLI, and the rest (`easybits-sandbox`, `easybits-agent`…): ```bash npx skills add https://easybits.cloud ``` Then paste this prompt, changing the end to whatever you need: ```text Install the EasyBits skill (npx skills add https://easybits.cloud) and use the CLI (npx -y @easybits.cloud/cli) to create a node sandbox, run my tests inside it and tell me the result. If there is no session, run `easybits login --json` and give me the link. ``` The agent will hand you a link to sign in the first time; it does the rest. ### Install ```bash npm i -g @easybits.cloud/cli # installs the `easybits` command npx -y @easybits.cloud/cli --help # no install (handy in CI and inside an agent) ``` Requires Node 22 or later. ### Log in ```bash easybits login # opens the browser; sign in and you're done easybits login --no-browser # only print the URL (e.g. for an agent to relay it) easybits login - < key.txt # alternative: an API key on stdin, no browser printenv EB_KEY | easybits login --with-token # same as `-` easybits usage # check it works: plan and storage easybits logout # forget the session and the key ``` `easybits login` uses OAuth2 with PKCE: it opens the browser, also prints the URL, and waits for you to come back; the session (with a refresh token) is stored in `~/.easybitsrc` and renews itself. The session renews itself before it expires, and once more if the API answers 401. If you run a command without a session from a terminal, the login starts on its own; without a terminal or with `--json` (an agent, CI) it exits with code `3`. Get an API key from the [Developer Dashboard](https://www.easybits.cloud/dash/developer). Precedence: the `EASYBITS_API_KEY` env var > the `--token` flag > the browser session > a key saved with `login -`. In CI, use the env var. The key never goes in argv: `ps` and your shell history would see it (that is why `login -` reads it from stdin and validates it before saving). `EASYBITS_URL` points the CLI at another server (default `https://www.easybits.cloud`); `baseUrl` in `~/.easybitsrc` works too. ### Sandboxes ```bash easybits sandboxes create --template node --name scratch # waits until running easybits sandboxes create --template node --size m --ttl 1800 --no-wait --dotenv .env easybits sandboxes ls easybits sandboxes get sb_abc123 # status, expiry, activity in progress easybits sandboxes exec sb_abc123 -- npm test # exits with the command's code easybits sandboxes logs sb_abc123 --unit myapp --lines 100 --since "10 min ago" --grep ERROR easybits sandboxes files ls sb_abc123 /data/work easybits sandboxes files write sb_abc123 /data/work/app.js ./app.js easybits sandboxes files read sb_abc123 /data/out.png --out out.png # 8 MB cap: larger files exit 1 ("truncated") easybits sandboxes files mkdir sb_abc123 /data/work/out easybits sandboxes files mv sb_abc123 /data/work/a.txt /data/work/out/a.txt easybits sandboxes files rm sb_abc123 /data/work/tmp -r --yes # -r for a folder easybits sandboxes bg start sb_abc123 --cwd /data/work -- npm run dev # background process; prints an execId easybits sandboxes bg ls sb_abc123 # recover an execId you lost easybits sandboxes bg status sb_abc123 exec_123 # status, exit code, its stdout/stderr easybits sandboxes bg kill sb_abc123 exec_123 # SIGTERM to the whole group, SIGKILL after --grace easybits sandboxes git clone sb_abc123 --repo https://github.com/you/app.git --dir /data/work/app --git-token '$secret:GITHUB_TOKEN' easybits sandboxes git status sb_abc123 --dir /data/work/app easybits sandboxes git commit sb_abc123 --dir /data/work/app --all -m "fix: checkout" easybits sandboxes codex login sb_abc123 # Codex on YOUR ChatGPT plan: shows a link + code, you sign in, saved to your vault easybits sandboxes codex connect sb_def456 # puts that session in another box (installs Codex if missing) easybits sandboxes codex save sb_abc123 # saves the renewed session back to the vault easybits sandboxes git push sb_abc123 --dir /data/work/app --git-token '$secret:GITHUB_TOKEN' easybits sandboxes git pull sb_abc123 --dir /data/work/app --rebase # exits 1 if there are conflicts easybits sandboxes git checkout sb_abc123 --dir /data/work/app --branch feature/x --create easybits sandboxes git log sb_abc123 --dir /data/work/app --limit 5 easybits sandboxes suspend sb_abc123 # sleeps to disk; resume wakes it easybits sandboxes resume sb_abc123 easybits sandboxes snapshot sb_abc123 --name before-upgrade easybits sandboxes destroy sb_abc123 --yes ``` Alias: `easybits sb …`. Everything after `--` in `exec` is the command, verbatim. On `create`: `--template` (default `ubuntu`), `--size s|m|l|xl` (gated by plan), `--ttl ` (lifetime before auto-destroy; `--timeout` in `exec` caps the command) and `--no-wait` (return without waiting for `running`). `bg` is for what outlives a call (a dev server, a long build): `exec` waits, `bg start` returns an `execId` right away; `nohup` inside `exec` does not survive. `git` runs inside the box with structured output: the token for a private repo goes in `--git-token`, best as `$secret:NAME` from your vault (a literal token is accepted with a warning: argv shows up in `ps`); a commit with no changes answers `nothingToCommit`, not an error. `logs` returns 200 lines by default; `--since` takes `journalctl` syntax. ### Hosting: permanent machines ```bash easybits machines ls easybits machines launch --machine shop --repo https://github.com/you/shop.git # deploy onto your machine (= launch_app) easybits machines launch --machine shop --archive ./build.tgz --prebuilt -m v2 # redeploy easybits deploy sb_abc123 -m "v1.2" # publish a release (= machines deploy) easybits machines releases sb_abc123 --limit 5 easybits machines logs sb_abc123 --lines 100 --grep ERROR easybits machines rollback sb_abc123 rel_789 # same machine, data untouched easybits machines secrets ls sb_abc123 easybits machines secrets set sb_abc123 --dotenv .env.production # KEY=VALUE lines printf 'API_KEY=%s\n' "$API_KEY" | easybits machines secrets set sb_abc123 --dotenv - easybits machines secrets unset sb_abc123 API_KEY easybits machines restart sb_abc123 # restart the app with the current secrets and runspec (seconds, no build) easybits machines adopt sb_abc123 --name shop-prod --unit app --import-env /app/secrets.env # register a box that already runs: EasyBits keeps its secrets and restarts it, never redeploys or releases it easybits machines get shop # size, status, whether it sleeps easybits machines tiers # hosting is by quote: how to ask for a machine easybits machines runspec get shop easybits machines runspec set shop --data /app/data --start 'node server.js' --port 8080 # merges with what is there easybits machines backups shop # daily data backups, kept 7 days easybits machines backup shop # take one now easybits machines redeploy shop --replace # recover: a new machine from the newest release easybits machines rm shop --yes # release (owner only): last backup, destroys the box easybits init --port 3000 # GitHub Actions workflow: deploy on every push ``` **Hosting is by quote** (write to soporte@easybits.cloud): machines are created by the EasyBits team or your agency and handed over to you. With your machine in place, everything above works the same; `launch` without `--machine` answers 403 `HostingByQuote`. `easybits deploy ` is short for `machines deploy `. Secrets go in a dotenv file or on stdin (`--dotenv -`), never in argv: `ps` and your shell history would see them. `secrets ls` shows names only; values are never readable. **Runspec** = how the app is built, started and backed up: `appDir`, `buildCommand`, `startCommand` or `unit`, `port`, `prebuilt`, `dataPaths`, `excludes`, `env` (non-secret). `runspec set` merges (env by key) and applies on the next deploy or restart; `--file rs.json` takes the output of `runspec get --json` as is, and flags win over it. **Without `--data` (dataPaths) nothing is backed up.** `redeploy` is recovery: it builds a NEW machine from `--release` (default: the newest); `--replace` releases the old one once the new one runs (it asks you to type the id). The new machine starts with no data. Changing size is quoted (soporte@easybits.cloud); a machine with an agreed price is not recreated on its own. `rm` asks you to type the id too: it takes a last backup and destroys the box. ### Account secrets (vault) ```bash easybits secrets ls # names and dates; values never come back easybits secrets set --dotenv .env.production # KEY=VALUE lines (- reads stdin) printf '%s' "$TOKEN" | easybits secrets set GITHUB_TOKEN # one value from stdin easybits secrets rm GITHUB_TOKEN --yes ``` The vault of your account (the same as /dash/developer/secrets and the `secret_*` MCP tools). A secret is used by name: `$secret:NAME` in an agent's MCP config or `--repo-token`, `machines launch --secret NAME`. Names are `[A-Z_][A-Z0-9_]*`; the same name replaces the value. Values never go in argv (`ps` and your shell history see it). `machines secrets` is different: values for ONE machine, which win over the vault. ### Your crons ```bash easybits crons create "Study reminder" --cron "30 8 * * *" --url https://www.ghosty.studio/api/v2/me/push \ --method POST --body '{"title":"Study time"}' --secret GHOSTY_PUSH_TOKEN easybits crons create "Report" --cron "0 9 * * 1" --times 4 --agent --prompt "Send me the sales summary" easybits crons create "Heads-up" --at 23:00 --url https://my-app.com/api/notice --method POST --dry-run # once; validates and says when easybits crons create "Heads-up" --in 2h --url https://my-app.com/api/notice --method POST easybits crons create "Review 1.0.10" --at 23:00 --run "pip install -q cryptography && python3 asc.py submit" \ --file scripts/asc.py --secret-file ASC_P8:~/.appstoreconnect/private_keys/AuthKey_X.p8 # command in a throwaway box easybits crons create "Daily signups" --cron "0 9 * * *" --run "python3 count.py" --file count.py --machine my-app # with my-app's env and secrets (its DATABASE_URL) easybits crons get "Review 1.0.10" # what it does, how it notifies you and the next run (--json: the whole object) easybits crons runs "Review 1.0.10" --logs --limit 5 # exit code and stdout/stderr of each run easybits crons wait "Review 1.0.10" --timeout 2h # waits for the next run and exits with its exit code easybits crons update "Review 1.0.10" --notify push,email --notify-on always # notifications (none removes them) easybits crons ls # yours: schedule, what it does, last and next run easybits crons update "Study reminder" --cron "0 7 * * 1-5" # only what you pass easybits crons run "Study reminder" # id or exact name; in the background easybits crons runs "Study reminder" # history with the full error easybits crons pause "Study reminder" # and resume easybits crons rm "Study reminder" --yes ``` They call a public https URL (with `--secret` a secret from your vault travels as a header, `Authorization: Bearer` by default) or send a turn to one of your agents. They repeat (`--cron`, at most every 5 min; they stop on their own with `--until ` or `--times N`) or run **once** (`--at "2026-10-18T23:00"` or `--at 23:00` = today, `--in 2h`): after running they turn off and stay in `ls` as "done", with their history. A time that already passed is an error, not "tomorrow". With `--run` the work is done by a **throwaway box** (python by default, `--template node|bun|ubuntu`): it mounts your `--file`s next to the command, each `--secret NAME` from your vault arrives as an env var, and each `--secret-file NAME:path` uploads that file as a secret **scoped to that cron** (no other cron, agent or machine can read it; it is deleted with the cron) and writes it at the same `~/` path in the box; success = exit 0, `--timeout` up to 600 s, the box is destroyed when done. `crons wait` stays until the next run (or the one in progress) finishes, prints its output and **exits with its code** (`exec`: the command's; the others: 0 if OK, 1 if not), so it fits an `&&` or a background process. `--notify push` sends a notification to the Ghosty app with the personal token in your `GHOSTY_PUSH_TOKEN` secret; `--notify email` writes to your account's email (never another address); by default only on failure, `--notify-on always` every time. `--dry-run` validates everything and shows the next 3 runs in local time without creating anything. `--tz` time zone (default America/Mexico_City), limit per plan. Same API as `/api/v2/crons`. ### Event inboxes ```bash easybits inbox create builds # your own webhook URL: anyone POSTs to it easybits inbox ls # your inboxes, URL and unread easybits inbox listen builds # live: one JSON line per event; reconnects on its own easybits inbox read builds # the unread ones, marked read (--all everything, --since from a cursor, --no-ack just look) easybits inbox update builds --retention 30 # rename (--name) or keep events longer; the URL stays easybits inbox rotate builds --yes # new URL; the old one stops accepting writes (if it leaked) easybits inbox rm builds --yes ``` An EasyBits webhook that reaches your terminal: whatever hits the URL reaches you live with `listen` (in Claude Code, run it with Monitor: each line wakes the agent) or waits for `read`. A cron writes to it with `--notify inbox:builds`. Anyone with the URL can write: keep it private. ### Platform crons (admins only) ```bash easybits crons ls --platform # status, schedule, last and next run easybits crons runs backup-machines # last 50 runs, with the full error easybits crons run purge-notifications # run now, in the background easybits crons pause check-hosting # its runs answer skipped easybits crons resume check-hosting ``` EasyBits' scheduled jobs (backups, purges, web app expiry): the same as the `/dash/admin/crons` panel. Needs a key with the `ADMIN` scope **and** being a platform superuser; any other account gets 403. The schedule lives in code and is not edited from here. ### Domains Two kinds. Your **account's** domains serve your websites at `.example.com` and, if you assign one, at the root: ```bash easybits domains ls easybits domains add example.com # prints the DNS records to create easybits domains verify example.com # TXT found → certificate issued easybits domains dns-auto example.com # DNS in Mailmask? writes the records for you (--undo restores) easybits domains apex example.com my-shop # serve a website at example.com and www (--clear removes it) easybits domains rm example.com --yes ``` A **sandbox's** domains point a domain at a port of a sandbox or machine: ```bash easybits sandboxes domains add sb_abc123 shop.example.com --port 3000 # prints the DNS record to create easybits sandboxes domains verify sb_abc123 shop.example.com # exits 1 until it is ready easybits sandboxes domains ls sb_abc123 easybits sandboxes domains rm sb_abc123 shop.example.com --yes ``` `easybits domains …` (the old form) still works: it runs `sandboxes domains` and says so on stderr. `domains dns-auto` without Mailmask connected exits 1 with the link to connect it once in a browser. ### Web Search, read, extract and crawl the web. Metered in **web queries** (packs at `/dash/packs?tab=web`); out of them it exits 1 with the link to buy. ```bash easybits web search dentist polanco --country mx # organic results: # / title / url (1 query) easybits web fetch https://example.com --markdown --main # body to stdout; --out page.md saves it (1 query) easybits web extract google_maps --input '[{"keyword":"dentist Polanco CDMX","country":"MX"}]' --limit 50 --wait easybits web extract mercadolibre --input '{"query":"iphone 15"}' --json # answers right away easybits web extract instagram_profiles --url https://instagram.com/easybits # async: prints the jobId easybits web extract-status j_abc123 # once done: one JSON record per line easybits web crawl https://docs.example.com --max-pages 5 --main # 1 query per page ``` `extract` charges 1 query per record returned (not per attempt) and most sources take 30-120 s: without `--wait` it returns the `jobId` and you check it with `extract-status`. Sources: `google_maps`, `mercadolibre`, `amazon_product`, `instagram_profiles`, `linkedin_company`… (or `--dataset ` from the catalog). ### Webhooks and API keys ```bash easybits webhooks ls easybits webhooks create https://example.com/hook --event file.created --event form.submitted # prints the secret ONCE easybits webhooks update 66f0c2a1b2c3d4e5f6a7b8c9 --event file.created,file.deleted # or --url, --pause, --resume easybits webhooks rm 66f0c2a1b2c3d4e5f6a7b8c9 --yes easybits keys ls # prefix only easybits keys create ci-deploy --scopes READ,WRITE --expires 2027-01-31 # prints the key ONCE easybits keys revoke ci-deploy --yes # by id, name or prefix ``` The webhook secret (`whsec_…`) and the new key (`eb_sk_live_…`) only appear at creation: with `--json` they come in `secret` and `raw`. A key can never create one with more permissions than its own (a READ key cannot mint a WRITE one, and only the dashboard or an ADMIN key grants ADMIN). `keys revoke` warns if it is the key the CLI itself is using. ### Sites (site builder) ```bash easybits sites ls # your /dash/sitios sites: kind, engine, URL easybits sites create --prompt "Landing for my dental clinic" # web app (TanStack) in its own machine easybits sites create --prompt "Task tracker with login" --stack next --json easybits sites create --name "Promo" --kind static # CDN website instead of a machine easybits sites model my-clinic # engine + model that build it (● = current) easybits sites model my-clinic claude-sonnet-5-5 # model applies to all your sites with that engine easybits sites theme get my-clinic # current colors (by name or id) easybits sites theme set my-clinic --theme dracula # a palette, no model turn jq .colors theme.json | easybits sites theme set my-clinic --colors - # or every token as #rrggbb ``` `create` returns `{id, name, kind, stack, template, previewUrl, url, editorUrl}`; `url` is `null` until you publish from the editor (building is free; a web app is charged when published). `--kind webapp` (default) gets its own machine with `--stack` `tanstack` (default), `next`, `react-router`, `remix`, `nuxt`, `sveltekit`, `astro` or `elysia`; `--template` (`consultorio`, `despacho`, `portafolio`, `lanzamiento`, `agente`) only exists for TanStack and React Router, and without it the prompt picks one. `--kind static` is a website on the CDN. The CLI rejects an unknown stack or template before calling the API. `theme` is the editor's «Tema» button: it rewrites the site's theme file (web app: `eb-theme.css`; static: the `eb-theme` block of `index.html`) and the preview picks it up. `--colors` needs every token (`primary`, `primary-light`, `primary-dark`, `secondary`, `accent`, `surface`, `surface-alt`, `surface-deep`, `on-surface`, `on-surface-muted`, `on-surface-deep`, `on-primary`, `on-secondary`, `on-accent`); an unknown palette answers `invalid_theme` and a site older than themes answers `no_tokens` (409). ### Documents Pages of HTML you write (the `/dash/documents` editor), published at a public URL and exported to PDF or PNG. The CLI does not generate with AI: write each page's HTML and set it. ```bash easybits documents ls --search quote # newest first; --limit up to 100 easybits documents create --name "ACME quote" --html cover.html --html prices.html # one page per file easybits documents create --name "Carousel" --format ig-feed # one blank 1080x1350 page easybits documents get "ACME quote" # format, URL and pages (by name or id) easybits documents pages ls "ACME quote" easybits documents pages get "ACME quote" 2 --out prices.html easybits documents pages set "ACME quote" 2 prices.html # - reads stdin easybits documents add-page "ACME quote" annex.html --after 2 --label Annex easybits documents rm-page "ACME quote" 3 --yes easybits documents reorder "ACME quote" 1 3 2 # every page, by number or id easybits documents deploy "ACME quote" # public URL (+ PDF) easybits documents export pdf "ACME quote" --out quote.pdf easybits documents export png Carousel --out ./slides --pages 1,2 easybits documents rm "ACME quote" --yes ``` A page is given by its number (1 = the first, as in the editor) or its id. `--format` is `letter` (default), `ig-feed`, `li-feed`, `ig-square`, `fb-square`, `ig-story`, `wsp-status`, `tiktok`, `slide-16-9` or `WxH` in px (100-10000); without `--html` the document starts with one blank page of that size. Pages go through the same path as `set_page_html`: a full HTML document (doctype, `