@moxt-ai/cli 0.3.2 → 0.3.3-moxt-run.1

package/README.md

@@ -152,6 +152,41 @@ moxt memory search -w <workspace-id> --teammate-id <teammateId> <query>
 moxt memory search -w <workspace-id> -l 10 <query>
 ```
 
+### run
+
+Run a local Codex or Claude Code process and capture the run as Moxt workspace context.
+
+```bash
+# Local-only capture, no API key required
+moxt run codex -- exec "summarize this repository"
+moxt run claude -- -p "summarize this repository"
+
+# Capture and upload source artifacts to the API key owner's personal space
+moxt run -w <workspace-id> codex -- exec "summarize this repository"
+moxt run -w <workspace-id> claude -- -p "summarize this repository"
+
+# Or set a default workspace for repeated uploads
+export MOXT_WORKSPACE_ID=<workspace-id>
+moxt run codex -- exec "summarize this repository"
+moxt run claude -- -p "summarize this repository"
+```
+
+Uploaded files are stored by Moxt under `Local Agent Sessions/<run-id>/` in personal space. For upload mode, `-w, --workspace` takes precedence over `MOXT_WORKSPACE_ID`; when neither is set, `moxt run` only writes the local capture artifact. The command does not accept a workspace destination selector for run uploads; the server chooses the storage location. `moxt run` preserves the local agent's stdin/stdout/stderr behavior and returns the agent's exit code even when upload cleanup fails afterward.
+
+Local run artifacts are written under the platform user data directory by default:
+macOS `~/Library/Application Support/moxt/runs/<run-id>/`, Linux `${XDG_DATA_HOME:-~/.local/share}/moxt/runs/<run-id>/`, and Windows `%LOCALAPPDATA%\Moxt\runs\<run-id>`. For tests or local debugging, override with `MOXT_RUN_OUTPUT_ROOT` or `MOXT_RUN_OUTPUT_DIR`.
+
+Real local-agent upload verification:
+
+```bash
+MOXT_HOST=web-api.moxt.ws \
+MOXT_API_KEY=moxt_... \
+MOXT_WORKSPACE_ID=<workspace-id> \
+pnpm --dir moxt-cli test:ai-e2e
+```
+
+By default this starts both real `codex` and real `claude`. Set `MOXT_RUN_AI_E2E_AGENTS=codex` or `claude` to run only one. For `*.moxt.ws` hosts behind Cloudflare Access, the runner reads the local `cloudflared` `moxt.ws` token when present; alternatively set `MOXT_CF_ACCESS_TOKEN`, `CF_ACCESS_TOKEN`, or Cloudflare Access service-token env vars.
+
 #### File command options
 
 | Option | Description |
@@ -178,7 +213,10 @@ Set the following environment variables:
 | Variable | Description |
 |----------|-------------|
 | `MOXT_API_KEY` | Your Moxt API key |
+| `MOXT_WORKSPACE_ID` | Default workspace ID for `moxt run` upload mode and AI E2E verification |
 | `MOXT_HOST` | API hostname (default: `api.moxt.ai`) |
+| `MOXT_CF_ACCESS_TOKEN` / `CF_ACCESS_TOKEN` | Optional Cloudflare Access token for protected development or testing hosts |
+| `MOXT_CF_ACCESS_CLIENT_ID` / `MOXT_CF_ACCESS_CLIENT_SECRET` | Optional Cloudflare Access service-token credentials |
 | `MOXT_TELEMETRY_DISABLED` | Set to `1` to disable anonymous usage telemetry |
 | `DO_NOT_TRACK` | Set to `1` to disable anonymous usage telemetry (community standard) |