Repository navigation
Sentry v1.0.2 — Windows Stable
Sentry v1.0.2 — Windows Stable
The production CLI is included in this release. Install once, open Desktop, and use sentry cli from PowerShell or Command Prompt to import/update projects, start Full or Targeted QA, inspect/cancel runs, and retrieve or export results. Commands use the same projects and runs as Desktop. The included Electron runtime runs the CLI; no Windows Node, pnpm, Git, or source checkout is required.
This patch combines the packaged CLI with consolidated current documentation. Existing v1.0.0/v1.0.1 archives remain unchanged and do not contain this packaged CLI. Existing users: follow “Update an existing installation” below.
Supported installation: Windows 11 x64 + WSL2, Ubuntu preferred. This is an unsigned ZIP with online Linux bootstrap, not an MSI/MSIX or offline installer. Setup requires internet and the Linux prerequisites below. Provider credentials are configured in Desktop; provider usage charges are separate.
1. WSL2 and Ubuntu
Run in PowerShell:
wsl.exe --list --verboseIf Ubuntu already exists, is initialized, and shows VERSION 2, keep it and continue. Otherwise run in PowerShell as Administrator:
wsl.exe --install -d UbuntuRestart if Windows requests it. Then use normal PowerShell:
wsl.exe --set-version Ubuntu 2
wsl.exe -d UbuntuComplete the Linux username/password prompts, then type exit to return to PowerShell. You do not need to remove WSL to install or update Sentry. See Microsoft WSL installation.
2. Linux prerequisites — commands from PowerShell
Skip this block if the selected Ubuntu already has Node >=22, pnpm 9.12.3, systemd user services, bubblewrap, and socat. Otherwise paste it into PowerShell. It installs packages inside Ubuntu using WSL root and the official NodeSource Node 22 repository when needed. If your distro has another name, change the Ubuntu selection in these blocks consistently.
& {
$ErrorActionPreference = 'Stop'
function Invoke-UbuntuRoot {
param([string[]]$LinuxArguments)
& wsl.exe -d Ubuntu -u root -- @LinuxArguments
if ($LASTEXITCODE -ne 0) { throw 'Ubuntu prerequisite installation stopped. Resolve the error before continuing.' }
}
function Get-UbuntuVersion {
param([string]$Tool)
try {
$version = & wsl.exe -d Ubuntu -- $Tool --version 2>$null
if ($LASTEXITCODE -eq 0) { return ([string]$version).Trim() }
} catch { }
return ''
}
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'update')
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'install', '-y', 'ca-certificates', 'curl', 'bubblewrap', 'socat', 'systemd', 'systemd-sysv')
$nodeVersion = Get-UbuntuVersion -Tool 'node'
if ($nodeVersion -notmatch '^v(\d+)\.' -or [int]$Matches[1] -lt 22) {
Invoke-UbuntuRoot -LinuxArguments @('install', '-d', '-m', '700', '/root/.cache/sentry-bootstrap')
Invoke-UbuntuRoot -LinuxArguments @('curl', '-fsSL', 'https://deb.nodesource.com/setup_22.x', '-o', '/root/.cache/sentry-bootstrap/node22.sh')
Invoke-UbuntuRoot -LinuxArguments @('bash', '/root/.cache/sentry-bootstrap/node22.sh')
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'install', '-y', 'nodejs')
}
$pnpmVersion = Get-UbuntuVersion -Tool 'pnpm'
if ($pnpmVersion -cne '9.12.3') {
Invoke-UbuntuRoot -LinuxArguments @('npm', 'install', '--global', 'pnpm@9.12.3')
}
$nodeVersion = Get-UbuntuVersion -Tool 'node'
if ($nodeVersion -notmatch '^v(\d+)\.' -or [int]$Matches[1] -lt 22 -or
(Get-UbuntuVersion -Tool 'pnpm') -cne '9.12.3') {
throw 'Node >=22 or pnpm 9.12.3 is unavailable inside Ubuntu. Installation stopped.'
}
& wsl.exe -d Ubuntu -- systemctl --user show-environment
if ($LASTEXITCODE -ne 0) {
throw 'Ubuntu systemd user services are unavailable. Follow the systemd guidance below, then rerun this block.'
}
Write-Host 'Ubuntu prerequisites installed. Continue with Install Sentry below.'
}If systemd user services are unavailable, follow Microsoft systemd guidance, preserving existing WSL configuration, and rerun the check.
3. Fresh install — download, verify, setup, and open
Paste the entire block into normal PowerShell from any folder, including System32. It automatically downloads the exact ZIP and checksum, verifies the pinned ZIP hash, manifest hash, full source identity, and every distribution file before executing the launcher, extracts into a separate version/source directory, sets up the matching runtime, provisions the pinned tools, and opens Desktop. A failure stops subsequent steps. Existing matching installation files are verified and reused; a tampered directory is refused.
& {
$ErrorActionPreference = 'Stop'
$name = 'sentry-1.0.2-2640efcd7874-windows-x64'
$expectedHash = '5265713af248297c543bf0d41093258bd0e7d8c177e0b1c544e733750347286f'
$expectedManifest = 'f5b2e5d93adb194a319df653502e8fa21a032b4542f4a4e9e6b7c87d34730ab3'
$source = '2640efcd78744cb02c517a405e648722e662bd60'
$download = Join-Path $env:USERPROFILE 'Downloads\Sentry-v1.0.2'
$destination = Join-Path $env:LOCALAPPDATA 'Sentry\releases'
$installation = Join-Path $destination $name
$zip = Join-Path $download ($name + '.zip')
$checksum = $zip + '.sha256'
$url = 'https://github.com/Mert1026/Sentry/releases/download/v1.0.2/'
New-Item -ItemType Directory -Path $download, $destination -Force | Out-Null
Write-Host 'Downloading the official ZIP and checksum...'
Invoke-WebRequest -UseBasicParsing -Uri ($url + $name + '.zip') -OutFile $zip
Invoke-WebRequest -UseBasicParsing -Uri ($url + $name + '.zip.sha256') -OutFile $checksum
if (-not (Test-Path -LiteralPath $zip -PathType Leaf) -or
-not (Test-Path -LiteralPath $checksum -PathType Leaf)) {
throw 'The ZIP or checksum file is missing. Installation stopped.'
}
$sidecarHash = ((Get-Content -LiteralPath $checksum -Raw).Trim() -split '\s+')[0]
$actualHash = (Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash
if ($sidecarHash -notmatch '^[a-fA-F0-9]{64}$' -or
$sidecarHash -ine $expectedHash -or $actualHash -ine $expectedHash) {
throw 'Checksum verification failed. Installation stopped.'
}
if (-not (Test-Path -LiteralPath $installation)) {
Expand-Archive -LiteralPath $zip -DestinationPath $destination
}
$manifestPath = Join-Path $installation 'distribution.json'
if ((Get-FileHash -LiteralPath $manifestPath -Algorithm SHA256).Hash -ine $expectedManifest) {
throw 'Distribution manifest mismatch. Installation stopped.'
}
$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
if ($manifest.sourceCommit -cne $source -or $manifest.version -cne '1.0.2' -or
$manifest.runtimeProtocol -ne 1 -or $manifest.targetPlatform -cne 'windows-x64') {
throw 'Release identity mismatch. Installation stopped.'
}
foreach ($file in $manifest.files.PSObject.Properties) {
$path = Join-Path $installation $file.Name
if ((Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash -ine $file.Value) {
throw ('Distribution file mismatch: ' + $file.Name)
}
}
Write-Host 'Approved checksum, manifest, source identity and files verified.'
$launcher = Join-Path $installation 'sentry.ps1'
foreach ($step in @('version', 'setup', 'tools', 'open')) {
Write-Host ('Sentry: ' + $step)
if ($step -in @('setup', 'tools')) {
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $launcher $step -Distro Ubuntu
} else {
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $launcher $step
}
if ($LASTEXITCODE -ne 0) {
throw ('Sentry ' + $step + ' stopped. Resolve the reported error, then paste this block again.')
}
}
Write-Host ('Installed at: ' + $installation)
Write-Host 'Check Environment is Connected. Provider requests can incur charges.'
$env:Path += ";$env:LOCALAPPDATA\Sentry\bin"
Write-Host "Use sentry open, sentry status, sentry doctor or sentry version from any folder."
}Keep the installed directory under %LOCALAPPDATA%\Sentry\releases; it is the application. Configure Settings → Providers, then check Environment is Connected and provider readiness. Installation/readiness checks do not start paid QA. A capabilities handshake alone does not establish runtime/provider readiness.
4. Update an existing installation — v1.0.0/v1.0.1 to v1.0.2
If your older installation has no registered sentry command, replace & sentry stop in the backup block with & powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\path\to\previous-installation\sentry.ps1" stop, using its actual absolute path.
- Finish active QA/retests or explicitly cancel them, and wait until they settle. Check Environment for your actual distro/data root. Keep the previous matched archive/runtime.
- In PowerShell, run the stopped-backup block below. It uses the standard current-user profile/data locations; change
$distroand$linuxDatato the actual values if customized. Allow enough space for a full backup plus the new archive and runtime. You can select another backup drive by changing$backup. - After backup succeeds, run the same complete v1.0.2 install block in step 3. It selects the new archive through setup and command registration. Do not extract over the old version or delete WSL/user data.
- Open a new PowerShell window, run the verification commands below, and inspect existing projects, completed history/results, exports, and provider settings in Desktop. Retain the stopped backup and previous matched installation until satisfied.
& {
$ErrorActionPreference = 'Stop'
# Use the distro and absolute data root shown by Sentry Environment.
$distro = 'Ubuntu'
$linuxData = (& wsl.exe -d $distro -- sh -c 'printf "%s/.local/share/sentry" "$HOME"').Trim()
if ($LASTEXITCODE -ne 0 -or -not $linuxData.StartsWith('/')) { throw 'Cannot determine Linux data root.' }
# If Environment shows a custom root, replace $linuxData above with that root.
& sentry stop
if ($LASTEXITCODE -ne 0) { throw 'Sentry must stop before backup.' }
& wsl.exe -d $distro -- sh -c 'if pgrep -f "[a]pps/runtime/dist/host.js" >/dev/null; then exit 1; fi'
if ($LASTEXITCODE -ne 0) { throw 'A runtime is still active. Close every Sentry instance first.' }
$backup = Join-Path ([Environment]::GetFolderPath('MyDocuments')) ('Sentry Backup ' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
New-Item -ItemType Directory -Path $backup -ErrorAction Stop | Out-Null
$linuxBackup = (& wsl.exe -d $distro -- wslpath -u ($backup.Replace('\', '/'))).Trim()
if ($LASTEXITCODE -ne 0 -or -not $linuxBackup.StartsWith('/')) { throw 'Backup path translation failed.' }
& wsl.exe -d $distro -- tar -czf ($linuxBackup + '/runtime-data.tar.gz') -C $linuxData .
if ($LASTEXITCODE -ne 0) { throw 'Linux backup failed. Do not upgrade yet.' }
& wsl.exe -d $distro -- tar -tzf ($linuxBackup + '/runtime-data.tar.gz') > $null
if ($LASTEXITCODE -ne 0) { throw 'Linux backup verification failed.' }
$profile = Join-Path $env:APPDATA '@qa\desktop'
if (-not (Test-Path -LiteralPath $profile -PathType Container)) { throw 'Desktop profile not found; check the actual profile location.' }
Copy-Item -LiteralPath $profile -Destination (Join-Path $backup 'desktop-profile') -Recurse -ErrorAction Stop
foreach ($part in @('launcher', 'bin')) {
$path = Join-Path $env:LOCALAPPDATA ('Sentry\' + $part)
if (Test-Path -LiteralPath $path) { Copy-Item -LiteralPath $path -Destination (Join-Path $backup $part) -Recurse -ErrorAction Stop }
}
Write-Host ('Stopped backup saved at: ' + $backup)
}After installing:
sentry version
sentry status
sentry doctor
sentry open
sentry cli capabilities --json
sentry cli project list --json
sentry cli agent list --jsonVersion must be 1.0.2, source must match the identity below, and Environment must be Connected. Setup preserves canonical data and encrypted provider settings; the packaged upgrade was exercised with disposable v1.0.1 completed history and synthetic DPAPI settings under the same Windows account/machine. This does not replace checking your own history. A stopped backup contains private project data and encrypted credentials: keep it private. Binary rollback does not reverse database migration; restore a compatible stopped data/profile backup with its matching runtime and Desktop according to the recovery policy.
5. Everyday launcher commands
These are individual command examples. Once setup registers Sentry, they work from any folder in a new PowerShell or Command Prompt window.
| Command | Purpose |
|---|---|
sentry open |
Open Desktop; required before operational CLI commands. |
sentry stop |
Request graceful shutdown; wait for active work first. |
sentry version |
Display installed archive version and full source identity. |
sentry status |
Show archive identity/process summary; use Environment for runtime readiness. |
sentry doctor |
Show diagnostics guidance without paid requests. |
sentry setup -Distro Ubuntu |
Install/repair this archive's matching runtime; requires idle components. |
sentry tools -Distro Ubuntu |
Provision pinned provider tools; requires idle components. |
sentry register-command |
Register this selected archive's command after moving its directory. |
sentry help |
Show launcher commands. |
sentry cli --help |
Show operational CLI syntax. |
If an already-open PowerShell cannot find the command:
$env:Path += ";$env:LOCALAPPDATA\Sentry\bin"
sentry version
sentry openIf you move the archive, invoke its full launcher path to register the new location:
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $env:LOCALAPPDATA "Sentry\releases\sentry-1.0.2-2640efcd7874-windows-x64\sentry.ps1") register-commandAdjust that path to where you moved it. sentry update deliberately refuses in pinned archives; updates use the new release's verified installation block.
6. CLI examples — project import and readiness
The following are individual examples, not a script to execute top to bottom. Replace proj_ID, run_ID, issue_ID, rev_ID, and retest_ID with actual IDs returned by commands. Replace source paths with existing folders. Keep Desktop open; credentials stay in Settings → Providers and are never supplied to the CLI.
sentry open
sentry cli capabilities --json
sentry cli agent list --json
sentry cli agent doctor opencode --json
sentry cli agent doctor deepseek --json
sentry cli agent doctor glm --json
sentry cli project add "C:\Projects\SampleApp" --json
sentry cli project list --json
sentry cli project show proj_ID --json
sentry cli project revisions proj_ID --json
sentry cli project doctor proj_ID --json
sentry cli project update proj_ID "C:\Projects\SampleApp" --jsonProject add/update returns data.projectId and data.revisionId. Import copies files into managed WSL storage and creates an immutable revision; the source folder remains yours. Generated caches are skipped, but .gitignore is not an import policy. Large imports may require multiple copies; both Windows backing-drive capacity and Linux free space matter. Removing managed projects does not immediately shrink WSL's virtual disk; Desktop's reclamation action is separate OS maintenance.
7. CLI examples — Full QA, Targeted QA, and polling
Choose one start example. These execute real providers and may incur charges. --agents selects the provider set. Configure them first. Full scans the project; Targeted limits included relative paths. --instructions supplies additional run guidance.
sentry cli run start proj_ID --mode full --agents opencode,deepseek,glm --json
sentry cli run start proj_ID --mode targeted --agents deepseek --paths src/auth,src/api --json
sentry cli run start proj_ID --mode full --agents opencode --instructions "Check input validation" --wait --timeout-ms 1800000 --json
sentry cli run list proj_ID --json
sentry cli run show run_ID --json
sentry cli run status run_ID --jsonStart is asynchronous by default: retain data.runId and data.operationId, then poll status. The runtime owns execution after the CLI exits. --wait observes the run until terminal status. --timeout-ms changes that run's engine timeout (1000–43200000 ms); omitted keeps 30 minutes. An uncertain start response may mean the paid run already exists: inspect run list/Desktop before any retry. Do not blindly retry RUN_MAY_HAVE_STARTED. Closing a CLI process does not cancel a canonical run.
8. CLI examples — results, JSON/log exports, cancellation, deletion
Retrieve results after a terminal status. Exports use the canonical runtime bytes and write the chosen local output file; create its parent directory first.
$reports = Join-Path ([Environment]::GetFolderPath("MyDocuments")) "Sentry Reports"
New-Item -ItemType Directory -Path $reports -Force | Out-Null
sentry cli run result run_ID --json
sentry cli run export run_ID --format json --out (Join-Path $reports "result.json") --json
sentry cli run export run_ID --format log --out (Join-Path $reports "result.log") --jsonUse these only when you intend to cancel/remove the selected item:
sentry cli run cancel run_ID --json
sentry cli project delete proj_ID --yes --jsonDeletion permanently removes Sentry-managed project data and history while preserving the original source folder. Active-work safety gates still apply. Cancellation is explicit and separate from deletion.
9. CLI examples — historical issues and retests
These commands inspect existing issue lineage and start/inspect/cancel a retest where a compatible historical issue exists. Retest execution uses real providers. They do not create issues from retired merger commands.
sentry cli issue list proj_ID --json
sentry cli issue show issue_ID --json
sentry cli issue history issue_ID --json
sentry cli retest start issue_ID --revision rev_ID --agents deepseek --wait --json
sentry cli retest show retest_ID --json
sentry cli retest cancel retest_ID --json10. Automation contract and errors
Always use --json for automation: stdout contains one JSON envelope; stderr contains human diagnostics. Parse stdout and branch on ok / error.code, never message wording. Capture the process exit status before running another command. run result returns canonical structured content inside data.result.
$responseText = sentry cli project list --json
$exitCode = $LASTEXITCODE
$response = $responseText | ConvertFrom-Json
if ($exitCode -ne 0 -or -not $response.ok) { throw ($response.error.code + ": " + $response.error.message) }
$response.data.projectsOptional informational client identity:
$env:SENTRY_CLI_CLIENT_NAME = "Automation client"
$env:SENTRY_CLI_CLIENT_VERSION = "1.0.0"
sentry cli capabilities --json| Exit | Meaning |
|---|---|
| 0 | Command success. |
| 1 | Internal/transport/protocol failure, including Desktop not running. |
| 2 | Invalid arguments or forbidden command. |
| 3 | Project/run/issue/source not found. |
| 4 | Conflict/retryable state, uncertain start, or response/export size limit. |
| 5 | Findings present for applicable completed execution commands. |
| 6 | Execution/provider readiness failure. |
| 7 | Partial execution. |
| 8 | Cancelled execution. |
An accepted asynchronous start is not proof the QA finished successfully. Use run status, run show, and run result. Common codes: SENTRY_DESKTOP_NOT_RUNNING → open Desktop; PROVIDER_NOT_READY → Settings/Environment; RUN_NOT_COMPLETE → poll; ACTIVE_RUN_EXISTS/PROJECT_LOCKED → settle active work; EXPORT_TOO_LARGE → canonical export exceeds the transport limit. JSON is never silently truncated. The canonical raw export limit is 6,000,000 bytes.
Production uses the Desktop named-pipe broker and the shared WSL runtime. It never creates a separate database and never selects direct/development transport from an environment override. Development simulation/retired merge/verifier commands are unavailable in the packaged CLI. Client names and pipe scope are informational, not authentication; the documented trust boundary includes same-user processes and does not claim a custom current-user-only pipe ACL. See the complete CLI contract and command reference, also included as CLI.md in the ZIP.
Artifact identity and verification
- Version: 1.0.2; target: windows-x64; runtime protocol: 1.
- Source: 2640efcd78744cb02c517a405e648722e662bd60.
- Git tree:
a2f74067c679cf1dcf37aa8f3df1ee08bce7bd10. - ZIP:
sentry-1.0.2-2640efcd7874-windows-x64.zip. - ZIP SHA256:
5265713af248297c543bf0d41093258bd0e7d8c177e0b1c544e733750347286f. - Manifest SHA256:
f5b2e5d93adb194a319df653502e8fa21a032b4542f4a4e9e6b7c87d34730ab3. - Complete verified manifest inventory: 337 files, including the production CLI and local guides.
Verification covers hosted quality/launcher/Windows archive jobs, complete local Linux and Windows regression lanes, physical sandbox trust tests, sealed archive/component identities, actual packaged Desktop/preload/renderer/IPC with its matching Linux runtime, CLI process argument/UTF-8/JSON/export behavior without Windows Node on PATH, canonical completed-history reads/exports, and isolated v1.0.1→v1.0.2 history/profile/synthetic encrypted-settings continuity. This is a prepared Windows/WSL host, not clean-machine provisioning. No paid-provider campaign or actual elevated disk compaction was executed for this release. No old tag or release asset is replaced.
Runtime schemas/migrations, provider/model/tool pins, credential encryption boundaries, and revision hashes are unchanged. OpenCode 1.18.32, DeepSeek SDK 0.1.5-rc.2, and Claude Code 2.1.270 remain pinned. Native Linux Desktop, macOS, signed installers, offline bootstrap, and automatic updating remain outside this release.
See v1.0.2 notes and the installation/recovery guide. Included INSTALL.md and CLI.md link to this exact source.