@moxt-ai/cli 0.2.0 → 0.3.1

package/README.md

@@ -103,7 +103,7 @@ moxt file get-url -w <workspace-id> --team-space-id <teamSpaceId> -p <path>
 # Resolve URL in a teammate space (by teammate ID)
 moxt file get-url -w <workspace-id> --teammate-id <teammateId> -p <path>
 
-# Upload a file
+# Upload a file by path
 moxt file put -w <workspace-id> -p <path> -l <local-path> [-r]
 
 # Upload a file to a teamspace (by name or ID)
@@ -113,6 +113,9 @@ moxt file put -w <workspace-id> --team-space-id <teamSpaceId> -p <path> -l <loca
 # Upload a file to a teammate space (by teammate ID)
 moxt file put -w <workspace-id> --teammate-id <teammateId> -p <path> -l <local-path> [-r]
 
+# Overwrite an existing file by its Moxt URL
+moxt file put --url <moxt-url> -l <local-path>
+
 # Create a directory
 moxt file mkdir -w <workspace-id> -p <path> [-r]
 moxt file mkdir -w <workspace-id> -s <teamspace-name> -p <path> [-r]
@@ -126,7 +129,7 @@ moxt file del -w <workspace-id> -s <teamspace-name> -p <path>
 
 | Option | Description |
 |--------|-------------|
-| `-w, --workspace <id>` | Workspace ID (required for all except URL mode) |
+| `-w, --workspace <id>` | Workspace ID (required for path mode) |
 | `-s, --space <name>` | Space name (`personal` or teamspace name) |
 | `--personal` | Use personal space (default when no space specified) |
 | `--team-space-id <id>` | Team space ID |
@@ -134,11 +137,12 @@ moxt file del -w <workspace-id> -s <teamspace-name> -p <path>
 | `-p, --path <path>` | File or directory path |
 | `-u, --url <url>` | Moxt file URL (e.g., `https://moxt.ai/w/{workspaceId}/{fileId}`) |
 | `-l, --local-path <path>` | Local file path (for upload) |
-| `-r, --recursive` | Create parent directories if needed |
+| `-r, --recursive` | Create parent directories if needed (path mode only) |
 
 > **Note**: `-s`, `--personal`, `--team-space-id`, and `--teammate-id` are mutually exclusive.
-> For `file read`, use either `--url` or `--workspace` with `--path`. They are mutually exclusive.
-> `file get-url` returns a stable Moxt URL (e.g., `https://moxt.ai/w/{workspaceId}/{fileId}`) for the given path; the URL is unchanged across writes to the same path and can be fed back into `file read --url`.
+> For `file read` and `file put`, use either `--url` or `--workspace` with `--path`. They are mutually exclusive.
+> `--url` with `file put` overwrites an existing file identified by the URL; it never creates new files. Use `--recursive` is not allowed in URL mode.
+> `file get-url` returns a stable Moxt URL (e.g., `https://moxt.ai/w/{workspaceId}/{fileId}`) for the given path; the URL is unchanged across writes to the same path and can be fed back into `file read --url` or `file put --url`.
 
 ## Configuration
 
@@ -147,7 +151,64 @@ Set the following environment variables:
 | Variable | Description |
 |----------|-------------|
 | `MOXT_API_KEY` | Your Moxt API key |
-| `MOXT_API_URL` | API endpoint (default: `https://api.moxt.ai`) |
+| `MOXT_HOST` | API hostname (default: `api.moxt.ai`) |
+| `MOXT_TELEMETRY_DISABLED` | Set to `1` to disable anonymous usage telemetry |
+| `DO_NOT_TRACK` | Set to `1` to disable anonymous usage telemetry (community standard) |
+
+## Telemetry
+
+Moxt CLI collects **anonymous usage data** by default to help us understand how the tool
+is used, prioritize features, and catch regressions. Telemetry is easy to turn off.
+
+### What we collect
+
+Every invocation of a Moxt CLI command may record:
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `command` / `subcommand` | `workspace` / `list` | Which command was invoked |
+| `cli_version` | `1.2.3` | Distribution of CLI versions in use |
+| `node_version` | `20.11.0` | Minimum-supported runtime planning |
+| `os` | `darwin` / `linux` / `win32` | OS support prioritization |
+| `arch` | `arm64` / `x64` | Architecture support prioritization |
+| `status` | `success` / `error` | Success and error rates |
+| `error_code` | `uncaught_exception` | Error classification (best-effort; may be dropped on crash) |
+| `is_ci` | `true` / `false` | Separate CI traffic from human usage |
+| Duration | `0.42` seconds | Performance tracking |
+
+User identification: telemetry is only sent while you are authenticated with a Moxt API
+key. Your **user ID is attached server-side** so that product decisions reflect real
+usage patterns.
+
+### What we do NOT collect
+
+- Command argument values (file paths, workspace IDs, emails, etc.)
+- File contents, directory names, or any data from your workspace
+- Environment variables
+- Standard output, standard error, or error messages
+
+### How to opt out
+
+Any one of the following disables all telemetry:
+
+```bash
+# Environment variable (recommended for CI)
+export MOXT_TELEMETRY_DISABLED=1
+
+# Or the community-standard variable
+export DO_NOT_TRACK=1
+
+# Or persist the choice
+moxt telemetry disable
+```
+
+Check current status with `moxt telemetry status`. Re-enable with `moxt telemetry enable`.
+
+### Where the data is sent
+
+Metrics are sent to `POST /openapi/v1/cli-metrics` on Moxt's API endpoint, authenticated
+with your API key. They are stored in Datadog and used to produce aggregated dashboards
+and reliability monitors.
 
 ## License