reallink-cli

Rust-based CLI for Reallink authentication, token workflows, and workspace file CRUD.

Install

npm install -g reallink-cli

On supported published platforms, npm installs a bundled prebuilt binary so install/update is fast. If a prebuilt binary is not available for your OS/arch, npm falls back to a one-time Rust release build during postinstall. 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

reallink login --base-url https://api.real-agent.link
reallink login --force # replace current saved session
reallink self-update --check
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 [email protected] --role member --expires-in-days 7
reallink org members --org-id org_xxx
reallink org add-member --org-id org_xxx --email [email protected] --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 [email protected] --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
reallink file download --asset-id ast_xxx --output ./downloads/report.json --resume
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

• 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:

plugins/unreal/
  index.json
  RealLinkUnreal/
    latest/
      RealLinkUnreal.zip
    0.1.0/
      RealLinkUnreal.zip

index.json / index.jsonc example:

{
  "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