reallink-cli 0.1.11 → 0.1.13

package/README.md

@@ -13,6 +13,8 @@ If a prebuilt binary is not available for your OS/arch, npm falls back to a one-
 After install, `reallink` runs the compiled binary directly (no per-command cargo compile step).
 CLI caches update metadata daily. To keep command startup fast, network update checks run during `reallink login` (or explicitly via `reallink self-update --check`) rather than every command.
 
+Output defaults to JSON for agent-friendly automation. You can switch to human text with `--format text`.
+
 ## Commands
 
 ```bash
@@ -23,18 +25,35 @@ reallink self-update
 reallink whoami
 reallink logout
 
+reallink org list
+reallink org create --name "My Org"
+reallink org get --org-id org_xxx
+reallink org update --org-id org_xxx --name "Renamed Org"
+reallink org delete --org-id org_xxx
+reallink org invites --org-id org_xxx
+reallink org invite --org-id org_xxx --email invitee@example.com --role member --expires-in-days 7
+reallink org members --org-id org_xxx
+reallink org add-member --org-id org_xxx --email member@example.com --role member
+reallink org update-member --org-id org_xxx --user-id usr_xxx --role admin
+reallink org remove-member --org-id org_xxx --user-id usr_xxx
+
 reallink project list --org-id org_xxx
 reallink project create --org-id org_xxx --name "new project" --description "optional"
 reallink project get --project-id prj_xxx
 reallink project update --project-id prj_xxx --name "renamed project"
 reallink project update --project-id prj_xxx --clear-description
 reallink project delete --project-id prj_xxx
+reallink project members --project-id prj_xxx
+reallink project add-member --project-id prj_xxx --email member@example.com --role viewer
+reallink project update-member --project-id prj_xxx --user-id usr_xxx --role editor
+reallink project remove-member --project-id prj_xxx --user-id usr_xxx
 
 reallink token list
 reallink token create --name "ci-token" --scope trace:read --scope trace:write
 reallink token revoke --token-id tok_xxx
 
 reallink file list --project-id prj_xxx
+reallink file tree --project-id prj_xxx
 reallink file get --asset-id ast_xxx
 reallink file stat --asset-id ast_xxx
 reallink file download --asset-id ast_xxx --output ./downloads/report.json
@@ -42,17 +61,49 @@ reallink file download --asset-id ast_xxx --output ./downloads/report.json --res
 reallink file upload --project-id prj_xxx --source ./local/report.json --path reports/daily
 reallink file mkdir --project-id prj_xxx --path reports/archive
 reallink file move --asset-id ast_xxx --file-name reports/archive/report.json
+reallink file move-folder --project-id prj_xxx --source-path reports/archive --target-path reports/2026
 reallink file remove --asset-id ast_xxx
 
+reallink logs status
+reallink logs consent --enable
+reallink logs tail --lines 120
+reallink logs upload --project-id prj_xxx --dry-run
+reallink logs upload --project-id prj_xxx --clear-on-success
+
 reallink tool list
 reallink tool register --manifest ./spec/tools/trace-placeholder.tool.jsonc
+reallink tool publish --tool-id trace.placeholder --channel ga --visibility public
 reallink tool enable --tool-id trace.placeholder --project-id prj_xxx
 reallink tool enable --tool-id trace.placeholder --user-id usr_xxx
 reallink tool run --tool-id trace.placeholder --project-id prj_xxx --input-file ./run-input.jsonc --idempotency-key run-001
 reallink tool runs --project-id prj_xxx
 reallink tool get-run --run-id trun_xxx
+reallink tool run-events --run-id trun_xxx --limit 200
+reallink tool run-events --run-id trun_xxx --stage-prefix workflow. --status succeeded
+
+reallink link unreal --project-id prj_xxx --uproject "D:/Games/MyGame/MyGame.uproject" --engine-root "D:/Epic/UE_5.4" --set-default
+reallink link list
+reallink link use --project-id prj_xxx
+reallink link doctor --project-id prj_xxx
+reallink link doctor --project-id prj_xxx --verify-remote
+reallink link paths --project-id prj_xxx
+reallink link open
+reallink link open --project-id prj_xxx --arg "-game" --arg "-log"
+reallink link run --project-id prj_xxx --commandlet ResavePackages --headless --log --arg "-AllowCommandletRendering"
+reallink link run --project-id prj_xxx --no-wait --arg "-game"
+reallink link remove --project-id prj_xxx
+reallink link plugin list
+reallink link plugin install --project-id prj_xxx --name RealLinkUnreal --version latest
+reallink link plugin install --project-id prj_xxx --name RealLinkUnreal --version latest --use-index
+reallink link plugin install --project-id prj_xxx --name RealLinkUnreal --version 0.1.0 --engine --force
+reallink link plugin install --project-id prj_xxx --name RealLinkUnreal --url https://cdn.example.com/RealLinkUnreal.zip --sha256 <hex>
 ```
 
+`reallink login` scope behavior:
+- By default it requests core/assets/trace/scheduler/admin scopes plus `tools:*`.
+- If the server rejects `tools:*` as invalid, CLI automatically retries with compatible scopes.
+- You can always pass explicit scopes via repeated `--scope`.
+
 `tool register`, `tool enable/disable` metadata, and `tool run --input-file` accept JSONC.
 
 ## Session Behavior
@@ -60,10 +111,108 @@ reallink tool get-run --run-id trun_xxx
 - Login stores a local session at:
   - Windows: `%APPDATA%\\reallink\\session.json`
   - Linux/macOS: `${XDG_CONFIG_HOME:-~/.config}/reallink/session.json`
+- Access token TTL: 15 minutes (auto-refreshed by CLI on 401).
+- Refresh/session TTL: 30 days.
 - You only need to log in again when the saved session is invalid/expired or you explicitly run `reallink logout`.
 - `reallink logout` revokes the current server session (`/auth/logout`) and clears the local session file.
 
+## CLI Logs & Crash Reports
+
+- Local logs are written under:
+  - Windows: `%APPDATA%\\reallink\\logs\\`
+  - Linux/macOS: `${XDG_CONFIG_HOME:-~/.config}/reallink/logs/`
+- Runtime log file: `runtime.jsonl`
+- Crash reports: `crash/crash-<epoch>.json`
+- Uploading logs requires explicit consent:
+  - `reallink logs consent --enable`
+- Upload destination path in project storage:
+  - `.reallink/logs/cli/runtime/*`
+  - `.reallink/logs/cli/crash/*`
+
+## Unreal Link Architecture
+
+`reallink link ...` provides a Vercel-style "link local project to remote project" workflow for local Unreal development.
+
+- `link unreal` creates/updates a binding between:
+  - remote Reallink `project_id`
+  - local `.uproject` path
+  - Unreal editor executable path
+  - optional engine root path
+- `link use` sets default link target.
+- `link open` launches local Unreal Editor using the stored mapping (plus optional forwarded args).
+- `link run` executes editor/commandlet runs against the linked Unreal target.
+- `link paths` resolves key local paths (uproject/editor/plugins/manifest) for scripting/agents.
+- `link doctor` performs local health checks and optional remote project verification.
+- `link list/remove` manage local bindings.
+- `link plugin list/install` pulls plugins from a public bucket index/zip and installs into project or engine scope.
+
+Local link metadata is stored at:
+- Windows: `%APPDATA%\\reallink\\unreal-links.json`
+- Linux/macOS: `${XDG_CONFIG_HOME:-~/.config}/reallink/unreal-links.json`
+
+`link unreal` verifies remote project access by default (requires `reallink login`); use `--no-verify-remote` for offline setup.
+
+`link unreal --sync-project` uploads a project-scoped manifest at:
+- `.reallink/link/unreal-link.latest.json`
+
+`link plugin install` default archive URL template:
+- `<base_url>/<plugin_name>/<version>/<plugin_name>.zip`
+
+Override with:
+- `--url <full_zip_url>`
+
+Index resolution:
+- `--use-index --index-path index.json` resolves plugin version/url from public index JSON/JSONC.
+
+Integrity:
+- `--sha256 <hex>` verifies downloaded zip checksum.
+- When `--use-index` is set and selected version contains `sha256`, CLI auto-verifies it.
+
+## Unreal Plugin Public Bucket Contract
+
+Recommended public bucket layout:
+
+```text
+plugins/unreal/
+  index.json
+  RealLinkUnreal/
+    latest/
+      RealLinkUnreal.zip
+    0.1.0/
+      RealLinkUnreal.zip
+```
+
+`index.json` / `index.jsonc` example:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "plugins": [
+    {
+      "name": "RealLinkUnreal",
+      "latest": "0.1.0",
+      "versions": [
+        {
+          "version": "0.1.0",
+          "archiveUrl": "https://real-agent.link/plugins/unreal/RealLinkUnreal/0.1.0/RealLinkUnreal.zip",
+          "sha256": "optional-checksum"
+        }
+      ]
+    }
+  ]
+}
+```
+
 ## Requirements
 
 - Prebuilt platforms: no Rust toolchain required.
 - Fallback build path (when no prebuilt binary exists): Rust toolchain (`cargo`) required.
+
+## Contributor Notes
+
+- CLI login scope constants are generated from shared contract source:
+  - source: `packages/shared/src/api-contract.ts`
+  - generator: `packages/reallink-cli/scripts/generate-contract.mjs`
+  - output: `packages/reallink-cli/rust/src/generated/contract.rs`
+- Run before build/release when scope contract changes:
+  - `pnpm --filter reallink-cli run contract:codegen`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reallink-cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Rust-based CLI for Reallink auth and API operations",
   "bin": {
     "reallink": "bin/reallink.cjs"
@@ -16,9 +16,10 @@
     "README.md"
   ],
   "scripts": {
-    "prepack": "node ./scripts/prepare-prebuilt.cjs",
+    "contract:codegen": "node ./scripts/generate-contract.mjs",
+    "prepack": "pnpm run contract:codegen && node ./scripts/prepare-prebuilt.cjs",
     "postinstall": "node ./scripts/postinstall.cjs",
-    "build": "cargo build --manifest-path ./rust/Cargo.toml --release",
+    "build": "pnpm run contract:codegen && cargo build --manifest-path ./rust/Cargo.toml --release",
     "dev": "node ./bin/reallink.cjs --help",
     "pack:local": "npm pack --json"
   },

package/rust/Cargo.lock

@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
 [[package]]
 name = "anstream"
 version = "0.6.21"
@@ -58,6 +64,15 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+dependencies = [
+ "derive_arbitrary",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -206,6 +221,21 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -216,6 +246,17 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "derive_arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -258,12 +299,28 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -343,6 +400,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -551,6 +614,16 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "indexmap"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
 [[package]]
 name = "ipnet"
 version = "2.11.0"
@@ -661,6 +734,16 @@ version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
 [[package]]
 name = "mio"
 version = "1.1.1"
@@ -910,7 +993,7 @@ dependencies = [
 
 [[package]]
 name = "reallink-cli"
-version = "0.1.11"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "clap",
@@ -919,8 +1002,10 @@ dependencies = [
  "reqwest",
  "serde",
  "serde_json",
+ "sha2",
  "tokio",
  "webbrowser",
+ "zip",
 ]
 
 [[package]]
@@ -1120,6 +1205,12 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e320a6c5ad31d271ad523dcf3ad13e2767ad8b1cb8f047f75a8aeaf8da139da2"
+
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -1972,8 +2063,37 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "zip"
+version = "2.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "crossbeam-utils",
+ "displaydoc",
+ "flate2",
+ "indexmap",
+ "memchr",
+ "thiserror 2.0.18",
+ "zopfli",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zopfli"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
+dependencies = [
+ "bumpalo",
+ "crc32fast",
+ "log",
+ "simd-adler32",
+]

package/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "reallink-cli"
-version = "0.1.11"
+version = "0.1.13"
 edition = "2021"
 description = "CLI for Reallink auth and token workflows"
 license = "MIT"
@@ -13,5 +13,7 @@ reqwest = { version = "0.12", default-features = false, features = ["json", "rus
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 json5 = "0.4"
+sha2 = "0.10"
 tokio = { version = "1.42", features = ["macros", "rt-multi-thread", "time", "fs", "io-util"] }
 webbrowser = "1.0"
+zip = { version = "2.2", default-features = false, features = ["deflate"] }

package/rust/src/generated/contract.rs

@@ -0,0 +1,52 @@
+// This file is auto-generated by packages/reallink-cli/scripts/generate-contract.mjs.
+// Do not edit by hand. Update packages/shared/src/api-contract.ts and re-run codegen.
+#![allow(dead_code)]
+
+pub const API_CONTRACT_VERSION: &str = "2026.03.1";
+pub const API_TOKEN_SCOPES: &[&str] = &[
+    "core:read",
+    "core:write",
+    "org:admin",
+    "project:admin",
+    "assets:read",
+    "assets:write",
+    "trace:read",
+    "trace:write",
+    "tools:read",
+    "tools:write",
+    "tools:run",
+    "scheduler:read",
+    "scheduler:write",
+];
+pub const CLI_DEFAULT_LOGIN_SCOPES: &[&str] = &[
+    "core:read",
+    "core:write",
+    "assets:read",
+    "assets:write",
+    "trace:read",
+    "trace:write",
+    "scheduler:read",
+    "scheduler:write",
+    "org:admin",
+    "project:admin",
+];
+pub const CLI_TOOL_SCOPES: &[&str] = &[
+    "tools:read",
+    "tools:write",
+    "tools:run",
+];
+pub const CLI_DEFAULT_LOGIN_SCOPES_WITH_TOOLS: &[&str] = &[
+    "core:read",
+    "core:write",
+    "assets:read",
+    "assets:write",
+    "trace:read",
+    "trace:write",
+    "scheduler:read",
+    "scheduler:write",
+    "org:admin",
+    "project:admin",
+    "tools:read",
+    "tools:write",
+    "tools:run",
+];

package/rust/src/generated/mod.rs

@@ -0,0 +1 @@
+pub mod contract;