sitemills-cli 1.0.11 → 1.0.13

package/README.md

@@ -108,9 +108,9 @@ SiteMills apps are built on declarative contracts, automatic RPC discovery, sand
 
 ```bash
 sitemills-cli login                    # 1. sign in through your browser
-sitemills-cli list                     # 2. find your app's ID
-sitemills-cli export <projectId>       # 3. download it into ./<projectId>
-cd <projectId>
+sitemills-cli list                     # 2. find your app's ID or site address
+sitemills-cli export <app>             # 3. download it (by ID or site address) into ./<app>
+cd <app>
 # 4. edit the files, then:
 sitemills-cli check                    #    compile your changes without saving anything
 sitemills-cli push                     #    upload your changes and update the branch preview
@@ -122,6 +122,7 @@ sitemills-cli deploy prod              # 5. go live (or dev / staging)
 - The `.sitemills/` folder is never uploaded, and it holds no secrets (your login token lives in `~/.sitemills`), so it's fine to commit it to your own git repo.
 - Need a specific branch or folder name? `sitemills-cli export <projectId> <branchId> <outputDir>`.
 - Every folder command also accepts the IDs explicitly: `sitemills-cli push <projectId> <branchId> <dir>`.
+- Wherever a command takes `<projectId>`, you can give the app's **site address** instead: the `<site-address>` in `https://<site-address>.sitemills.com`. `sitemills-cli list` shows both. Older apps have the same project ID and site address; newer apps have a separate project ID.
 
 ### Starting from your own code
 
@@ -146,17 +147,17 @@ SiteMills clearly distinguishes between the **Platform Management Dashboard** an
 
 | Purpose | URL / Hostname Pattern | Example |
 |---|---|---|
-| **Production Live Application (`PROD`)** | `https://<projectId>.sitemills.com` | `https://gradeprep.sitemills.com` |
-| **Staging Live Application (`STAGING`)** | `https://<projectId>-staging.sitemills.com` | `https://gradeprep-staging.sitemills.com` |
-| **Development Live Application (`DEV`)** | `https://<projectId>-dev.sitemills.com` | `https://gradeprep-dev.sitemills.com` |
-| **Branch Preview URL** | `https://<projectId>--<branchId>.sitemills.com/?preview_token=...` | `https://gradeprep--e4d7df82-24b2-4e3b-97ce-5aa4ba5a79ec.sitemills.com` |
+| **Production Live Application (`PROD`)** | `https://<site-address>.sitemills.com` | `https://gradeprep.sitemills.com` |
+| **Staging Live Application (`STAGING`)** | `https://<site-address>-staging.sitemills.com` | `https://gradeprep-staging.sitemills.com` |
+| **Development Live Application (`DEV`)** | `https://<site-address>-dev.sitemills.com` | `https://gradeprep-dev.sitemills.com` |
+| **Branch Preview URL** | `https://<site-address>--<branchId>.sitemills.com/?preview_token=...` | `https://gradeprep--e4d7df82-24b2-4e3b-97ce-5aa4ba5a79ec.sitemills.com` |
 | **Platform Project Console / IDE** | `https://sitemills.com/project/<projectId>` | `https://sitemills.com/project/gradeprep` |
 | **Project Planning Board** | `https://sitemills.com/project/<projectId>/planning` | `https://sitemills.com/project/gradeprep/planning` |
 | **Project Settings / Variables** | `https://sitemills.com/project/<projectId>/settings` | `https://sitemills.com/project/gradeprep/settings` |
 
 > [!WARNING]
 > **Important URL Distinction:**
-> - **Live Deployed Websites**: Web applications deployed to SiteMills are hosted on subdomains: `https://<projectId>.sitemills.com` for Production, `https://<projectId>-staging.sitemills.com` for Staging, and `https://<projectId>-dev.sitemills.com` for Dev.
+> - **Live Deployed Websites**: Web applications deployed to SiteMills are hosted on subdomains of their site address: `https://<site-address>.sitemills.com` for Production, `https://<site-address>-staging.sitemills.com` for Staging, and `https://<site-address>-dev.sitemills.com` for Dev. Build site links from the site address (`sitemills-cli info` shows it), never from the project ID.
 > - **Platform Console Dashboard**: The web dashboard is located at `https://sitemills.com/project/<projectId>` (singular `/project/`, **not** plural `/projects/`). Never link to `https://sitemills.com/projects/<projectId>` as that is an internal API route prefix (`/api/v1/projects/...`) and will fail to load in the browser.
 
 ## Preview Access Tokens & Non-Production Environments
@@ -184,7 +185,7 @@ Non-production environments (**DEV**, **STAGING**, and **Branch Previews**) are
    - Their active session cookie (`USER_AUTH_TOKEN`) authorizes access directly to all permitted project environments.
 
 4. **Production Environments (`PROD`)**:
-   - Production URLs (`https://<projectId>.sitemills.com`) are always public and do not require authentication or preview tokens.
+   - Production URLs (`https://<site-address>.sitemills.com`) are always public and do not require authentication or preview tokens.
 
 ---
 
@@ -262,11 +263,10 @@ sitemills-cli <command> [options]
   ```bash
   sitemills-cli seed <projectName> [outputDir]
   ```
-- **Folder commands** (`check`, `push`, `commit`, `deploy`): `[dir]` defaults to the current folder and must be a folder created by `export` or `import`. You can always pass `<projectId> <branchId> <dir>` instead.
+- **Folder commands** (`check`, `push`, `commit`, `deploy`): `[dir]` defaults to the current folder and must be a folder created by `export` or `import`. You can always pass `<projectId> [dir]` instead.
 - **export**: Download an app's code into a folder and link the folder to the app, so `check`, `push`, `commit`, and `deploy` work inside it without IDs.
   ```bash
   sitemills-cli export <projectId> [outputDir]              # Working Draft into ./<projectId> by default
-  sitemills-cli export <projectId> <branchId> <outputDir>
   ```
 - **commit** (or **save-snapshot**): Quickly save a code snapshot to a branch without triggering cloud compilation or tests (~100ms). Only files that differ from the remote branch are uploaded, and remote files missing locally are deleted (pass `--no-prune` to keep them). Automatically saves metadata to `.sitemills/build.json` in the local directory and records the build in `~/.sitemills/builds.json`.
   ```bash
@@ -282,7 +282,7 @@ sitemills-cli <command> [options]
   ```
 - **compile**: Trigger manual project code compilation for a branch and inspect diagnostics. Pass `--skip-tests` to bypass testing.
   ```bash
-  sitemills-cli compile <projectId> [--branch <branchId>] [--skip-tests]
+  sitemills-cli compile <projectId> [--skip-tests]
   ```
 - **deploy**: Deploy a branch to an environment (`dev`, `staging`, or `prod`).
   ```bash
@@ -294,7 +294,7 @@ sitemills-cli <command> [options]
   ```
 - **version-history**: View the timeline of code versions and checkpoints for a specific branch.
   ```bash
-  sitemills-cli version-history <projectId> [branchId] [--limit <limit>]
+  sitemills-cli version-history <projectId> [--limit <limit>]
   ```
 - **delete**: Delete a project on SiteMills.
   ```bash
@@ -334,7 +334,7 @@ Manage background and scheduled jobs defined in `contracts/jobs.json` and implem
 
 - **seed-db**: Seed database records for a project/branch from a JSON file.
   ```bash
-  sitemills-cli seed-db <projectId> <branchId> <dataFile.json>
+  sitemills-cli seed-db <projectId> <dataFile.json>
   ```
 - **data-copy** (or **clone-scope**): Clone all database collections and records from a source environment/scope to a target scope (e.g. from PROD to STAGING).
   ```bash
@@ -343,7 +343,7 @@ Manage background and scheduled jobs defined in `contracts/jobs.json` and implem
   ```
 - **data-op**: Execute structured database operations (query, count, seed, mutation preview, mutation apply, or inline Lua execution).
   ```bash
-  sitemills-cli data-op <projectId> <payloadJsonOrFile> [--branch <branchId>] [--env <environment>] [--mock-user <email>]
+  sitemills-cli data-op <projectId> <payloadJsonOrFile> [--env <environment>] [--mock-user <email>]
   ```
   *Inline Example:*
   ```bash
@@ -362,11 +362,11 @@ Manage background and scheduled jobs defined in `contracts/jobs.json` and implem
 
 - **logs**: Fetch runtime logs with optional branch, environment, and level filtering.
   ```bash
-  sitemills-cli logs <projectId> [--branch <branchId>] [--env <environment>] [--level <INFO|WARN|ERROR>] [--limit <limit>]
+  sitemills-cli logs <projectId> [--env <environment>] [--level <INFO|WARN|ERROR>] [--limit <limit>]
   ```
 - **workflows**: List recent AI/agentic workflows run on the project, including prompts, token consumption, and status.
   ```bash
-  sitemills-cli workflows <projectId> [--branch <branchId>] [--limit <limit>]
+  sitemills-cli workflows <projectId> [--limit <limit>]
   ```
 - **credits**: Query remaining credit and token usage balances for a project.
   ```bash
@@ -513,7 +513,6 @@ How the CLI stays current depends on how you installed it:
 - `--skip-tests`: Bypass automated test suite execution during push and compilation.
 - `--params <json>`: JSON payload parameters for on-demand job execution (`jobs run`).
 - `--reason <reason>`: Reason message when pausing a background job (`jobs pause`).
-- `--branch <branch>`: Target branch ID or branch data scope.
 - `--env <environment>`: Target environment name (`DEV`, `STAGING`, or `PROD`).
 - `--filter <filter>`: JSON query filter for `run-lua` (e.g. `'{"status":"pending"}'`).
 - `--dry-run`: Execute Lua script as a dry run simulation without applying database writes.