@envshipcom/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnvShip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# EnvShip CLI
+
+EnvShip delivers encrypted `.env` bundles to CI, Docker, VPS, Laravel, Node, and other deployments. Humans set up workspaces, projects, bundles, channels, and access in the OAuth/passkey Dashboard. The open source CLI is the deploy and automation surface: connect CLI Workstations, install scoped machines, pull encrypted current bundles, and run processes without sending plaintext secrets to EnvShip.
+
+Package name: `@envshipcom/cli`  
+Binary command: `envship`
+
+## Install
+
+```bash
+pnpm dlx @envshipcom/cli --help
+npx @envshipcom/cli --help
+npm install -g @envshipcom/cli
+```
+
+## Quick Start
+
+For people:
+
+```bash
+envship auth connect --code <one-time-code>
+envship channel pull web/staging --out .env --force
+```
+
+Dashboard generates short-lived setup codes after a trusted device unlock. The CLI saves a local Workstation identity and handles the encryption details behind the scenes.
+
+For one-off servers:
+
+```bash
+envship machine install --name web-production --channel web/production
+envship channel pull web/production --out .env --force
+envship channel run web/production -- npm start
+```
+
+For CI, autoscaling, and fresh spinups:
+
+```bash
+envship machine deploy-token-create --project <project-id> --channel web/production
+ENVSHIP_DEPLOY_TOKEN=edt_...
+envship machine install --deploy-token "$ENVSHIP_DEPLOY_TOKEN" --name web-production
+envship channel pull web/production --out .env --force
+```
+
+For live file updates from the CDN runtime path:
+
+```bash
+envship envsync watch --channel web/production --out .env
+envship envsync install --channel web/production --out /etc/envship/web.env --interval 60s
+```
+
+Check runtime compatibility:
+
+```bash
+envship update check
+envship update autoupdate off
+envship update autoupdate on
+```
+
+## Security Model
+
+- OAuth proves account identity; it does not decrypt secrets by itself.
+- Human browser editing unlocks with a Trusted Browser Device in the Dashboard. Passkey PRF is the high-security upgrade where supported.
+- Browser Dashboard access is included with the signed-in account. CLI Workstations cover trusted coding environments like a laptop, desktop, dev container, or Codespace.
+- Machine identities are project-scoped installed online servers/runners, separate from human CLI Workstations.
+- Runtime slots are shared by active manual machine identities and reusable deploy-token reserved capacity. Use the pool in any mix, such as all manual machines, all reserved deploy-token capacity, or a combination.
+- For autoscaling platforms such as AWS Elastic Beanstalk, reserve enough Runtime slots on the reusable deploy token for the number of active instances that token is allowed to run.
+- If active runtime identities exceed the workspace plan, EnvShip allows a 7-day upgrade grace before blocking new machine installs. The recommended PayPal upgrade path is a separate difference subscription unless billing can be consolidated safely.
+- Reusable deploy tokens are separate bootstrap credentials for fresh installs/autoscaling. They reserve Runtime slots while active, are shown once, hashed server-side, scoped to allowed channels, revocable, rotatable, and audited. Rotating a token does not consume another slot.
+- Runtime pulls prefer public encrypted current descriptors and immutable encrypted bundle objects from the EnvShip CDN. The public CDN contains ciphertext, hashes, and signed runtime metadata only.
+- Workspace admins may define encrypted identity overlays for one CLI Workstation, machine, or deploy token. The CLI decrypts the shared channel env locally, applies the authorized identity overlay locally, and writes or runs with the merged result.
+- EnvShip never receives plaintext dotenv values, private vault keys, passkey PRF outputs, vault unlock keys, private machine keys, or unwrapped bundle keys.
+
+## Commands
+
+### `envship auth login`
+
+Creates a device approval code and opens the browser authorization URL.
+
+```bash
+envship auth login
+envship auth login --headless
+```
+
+### `envship auth connect`
+
+Connects a CLI Workstation with a one-time Dashboard code. Browser Dashboard use is included with the account; each connected CLI Workstation counts against the user's workstation allowance.
+
+```bash
+envship auth connect --code cli_xxxxxxxxxxxxxxxxxxxx
+```
+
+### `envship auth whoami` and `envship auth logout`
+
+Inspect or clear the local EnvShip session and machine credential.
+
+```bash
+envship auth whoami
+envship auth logout
+```
+
+### `envship setup`
+
+Creates the first workspace, project, bundle, and channels for the signed-in session. Dashboard onboarding is the recommended path for production setup because it also walks humans through Authorized Devices and plan selection.
+
+```bash
+envship setup --workspace "My Workspace" --project "My First Project" --bundle web --channels staging,production
+```
+
+### `envship machine install`
+
+Installs a scoped machine identity. Use interactive approval for one-off servers, or a reusable deploy token for CI/autoscaling/fresh spinups. Machine identities are the installed runtime identities.
+
+```bash
+envship machine install --name github-actions-production --channel web/production
+envship machine install --deploy-token "$ENVSHIP_DEPLOY_TOKEN" --name elastic-beanstalk-web
+```
+
+Inspect or revoke a machine:
+
+```bash
+envship machine status
+envship machine revoke --yes
+envship machine revoke --id 00000000-0000-0000-0000-000000000000 --yes
+```
+
+### Deploy Tokens
+
+Create, list, revoke, or rotate reusable deploy tokens. Tokens are shown once; store them like any other production deploy credential. Listing and status output never re-show token values. Active deploy tokens reserve Runtime slots for autoscaling/fresh installs while manual machine identities use Runtime slots directly.
+
+```bash
+envship machine deploy-token-create --project <project-id> --channel web/production
+envship machine deploy-token-list --project <project-id>
+envship machine deploy-token-revoke <token-id> --yes
+envship machine deploy-token-rotate <token-id> --yes
+```
+
+### `envship channel pull`
+
+Fetches the current encrypted channel, verifies signed hashes, decrypts locally with the installed Workstation or machine identity, applies any authorized identity overlay, and writes dotenv output.
+
+```bash
+envship channel pull web/staging --out .env --force
+envship channel pull web/staging --out -
+```
+
+When the channel has a public encrypted descriptor, the CLI fetches the descriptor and bundle from the CDN path so runtime pulls do not hit Worker/D1 on every request. If the descriptor is unavailable in local/debug environments, the CLI falls back to the Worker pull route. Production runtime pulls always respect the CDN descriptor path; Dashboard Deploy History shows whether a saved encrypted version is runtime-ready or waiting for CDN refresh.
+
+### `envship channel run`
+
+Runs a command with locally decrypted env values, including any authorized identity overlay.
+
+```bash
+envship channel run web/production -- npm run deploy
+```
+
+### `envship envsync`
+
+EnvSync keeps an already-authorized channel output file current without polling Worker/D1.
+
+Watch mode runs in the foreground:
+
+```bash
+envship envsync watch --channel web/production --out .env
+envship envsync watch --channel web/production --out .env --on-change -- npm run reload
+```
+
+Daemon mode writes a service configuration for your operating system. Review and install it with your normal service manager:
+
+```bash
+envship envsync install --channel web/production --out /etc/envship/web.env --interval 60s
+envship envsync status --name web-production
+envship envsync uninstall --name web-production --yes
+```
+
+EnvSync uses the local scoped runtime profile created by machine install or deploy-token install, then checks the stable public descriptor URL with cache validators. If nothing changed, it skips immutable bundle downloads. If a descriptor changes, EnvSync verifies the channel scope and encrypted bundle hash, decrypts locally, writes the target file atomically, and only then runs an optional `--on-change` hook.
+
+There is no freshness bypass. EnvSync remains cache-respecting by design so runtime traffic stays on R2/CDN instead of becoming a Worker/D1 hot path.
+
+### `envship update`
+
+Checks the signed cacheable runtime-version descriptor and reports whether this CLI is current, recommended to update, or below the minimum supported version. AutoUpdate is on by default for Free/FreeEnv-compatible identities where supported. Paid workspaces may pin or disable AutoUpdate per Workstation or machine, but EnvShip will warn when a pinned runtime approaches a compatibility cutoff.
+
+```bash
+envship update check
+envship update autoupdate off
+envship update autoupdate on
+```
+
+### Channel Inspection And Rollback
+
+```bash
+envship channel list
+envship channel versions web/staging
+envship channel rollback web/staging --version-id 00000000-0000-0000-0000-000000000000 --yes
+```
+
+### Grants And Administration
+
+```bash
+envship grant create web/staging --keyset kst_example --preset editor
+envship grant list web/staging
+envship invite create --email teammate@example.com --role viewer
+envship invite list
+envship member list
+envship project list
+envship audit list
+envship billing status
+envship billing checkout --plan pro
+envship doctor
+```
+
+Use `--json` on any command for machine-readable output. Commands that intentionally write decrypted dotenv data to stdout, such as `envship channel pull --out -`, cannot be combined with `--json`.
+
+## Configuration
+
+EnvShip stores local CLI config at:
+
+```text
+~/.envship/config.json
+```
+
+The config file may contain a session cookie and machine signing credential. It is written with owner-only permissions where the operating system supports them. Do not share it, paste it into support requests, or commit it.
+
+Safe inspection:
+
+```bash
+envship config get
+envship config get apiBaseUrl
+```
+
+`envship config get` redacts credential-bearing fields and only exposes safe config keys.
+
+Useful environment variables:
+
+- `ENVSHIP_API_BASE_URL`: API origin. Defaults to `https://api.envship.com`.
+- `ENVSHIP_APP_URL`: browser app origin. Defaults to `https://envship.com`.
+- `ENVSHIP_SESSION`: session cookie value for local tests or explicit automation.
+- `ENVSHIP_DEPLOY_TOKEN`: reusable deploy token for non-interactive machine install.
+- `ENVSHIP_RUNTIME_VERSION_SIGNING_PUBLIC_JWK`: optional local trust anchor for verifying signed runtime-version metadata in development and staging.
+
+Do not commit `ENVSHIP_SESSION`, `ENVSHIP_DEPLOY_TOKEN`, or `~/.envship/config.json`.
+
+## Troubleshooting
+
+- `Channel web/staging was not found`: run Dashboard setup or `envship setup`, then check that the machine is scoped to that channel.
+- `machine_not_configured`: run `envship machine install` or install with a reusable deploy token.
+- `deploy_token_invalid`: create or rotate a deploy token from a project manager/owner session.
+- `json_stdout_conflict`: write decrypted dotenv output to a file, or omit `--json` when using `--out -`.
+- `envship doctor --json` exits nonzero when readiness checks fail, while keeping stdout as one parseable JSON object.
+- `Encrypted bundle hash mismatch`: EnvShip refused to decrypt because the fetched object did not match signed metadata.
+- `missing_publish_capability`: your user or machine is not allowed to publish this channel.
+- Local development should prefer `--api-url http://127.0.0.1:8787` for CLI smoke checks. The CLI does not disable TLS verification globally.
+
+## npm Publish Checklist
+
+1. Create or join the npm organization/scope `envshipcom`.
+2. Run `npm login`.
+3. Confirm package metadata in `packages/cli/package.json`.
+4. Build: `pnpm --filter @envshipcom/cli build`.
+5. Dry run: `npm pack --dry-run` from `packages/cli`.
+6. Run package smoke from the repo root: `pnpm smoke:cli-package`.
+7. Publish only after explicit approval: `npm publish --access public` from `packages/cli`.
+8. Verify: `https://www.npmjs.com/package/@envshipcom/cli`.
+9. Test from a clean directory: `pnpm dlx @envshipcom/cli --help` and `npx @envshipcom/cli --help`.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "index.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../src/index.ts"
+  ],
+  "names": [],
+  "mappings": ""
+}