@tutti-os/nexight-devops

nexight-devops is a TypeScript CLI for Nexight DevOps workflows.

Install

npm install -g @tutti-os/nexight-devops

Commands

nexight-devops --help
nexight-devops --version
nexight-devops doctor
nexight-devops onboard
nexight-devops onboard --set-mode aws
nexight-devops onboard --set-mode gh
nexight-devops onboard --set-mode locale
nexight-devops onboard --set-mode admin
nexight-devops onboard --set-mode datafinder
nexight-devops update-version
nexight-devops admin auth login
nexight-devops admin auth whoami
nexight-devops admin system health
nexight-devops admin app list --brand nextop --query design
nexight-devops admin app detail --brand nextop --app-id vibe-design --include latest,versions
nexight-devops admin computer list --connection online --query <name>
nexight-devops admin computer list --connection online --owner-query <username-or-email>
nexight-devops admin computer detail --computer-id <computer-id>
nexight-devops admin computer logs <computer-name-or-id> --range 1h
nexight-devops admin computer logs --owner-query <username-or-email> --range 1h
nexight-devops admin computer logs <computer-name-or-id> --from <timestamp> --to <timestamp>
nexight-devops admin computer log-recall list --computer-id <computer-id>
nexight-devops admin computer log-recall download --computer-id <computer-id> --task-id <task-id>
nexight-devops datafinder auth check
nexight-devops datafinder dashboard export --count 100
nexight-devops datafinder query shared-agent-summary --count 100
nexight-devops datafinder query p2p-health --count 100
nexight-devops datafinder query exec ./query.mjs -- arg1 arg2
nexight-devops ppe-lane deploy
nexight-devops ppe-lane destroy
nexight-devops ppe-lane status
nexight-devops ppe-lane status --all
nexight-devops release prepare
nexight-devops release hotfix
nexight-devops release approve
nexight-devops release rollback
nexight-devops release rollback tutti-server

Function overview

• doctor checks that the CLI can start.
• onboard installs or configures Homebrew, GitHub CLI authentication, AWS SSO, management backend login, DataFinder OpenAPI, and the CLI locale. Use --set-mode <mode> to configure only one integration.
• update-version checks npm for a newer CLI version and upgrades it with the detected package manager.
• admin auth logs into, logs out of, and inspects the management backend token.
• admin system health checks management backend health.
• admin app list/detail queries App Center applications and optionally their versions.
• admin computer list/detail finds Tutti Computers and reports their current connection state.
• admin computer logs resolves an online Computer and bundles recall, polling, and temporary download into one Agent-friendly workflow.
• admin computer log-recall exposes the lower-level task operations for troubleshooting and recovery.
• datafinder validates access, reads dashboards/reports, runs trusted local JavaScript queries, and exposes fixed reliability queries.
• ppe-lane deploy deploys selected backend repositories to a PPE lane. Supported targets are tutti-server, zk-admin-server, account, and zk-websocket.
• ppe-lane destroy checks existing lane instances and triggers destroy workflows after a lane-name confirmation. tutti-server must be selected explicitly for destruction.
• ppe-lane status queries AWS Cloud Map for one lane, or all lanes with --all, including tutti-server.
• release prepare, release hotfix, and release approve run the controlled release lifecycle through GitHub Actions and approval issues.
• release rollback lets you choose tutti-server interactively; release rollback tutti-server selects it directly. The command reads the current production image and up to ten recent Helm deployments directly when local read access to the production cluster is available. Otherwise it retrieves the verified list through GitHub Actions. The selected image is always revalidated and restored by GitHub Actions, followed by health checks. Use --revision <number> --yes with the explicit repository for scripted selection and confirmation.

Controlled Release

nexight-devops release prepare
nexight-devops release hotfix
nexight-devops release approve

• release prepare starts a controlled release for a target repo and creates the approval issue.
• release hotfix starts a controlled hotfix flow and supports an explicit override when release-branch patches have not yet been absorbed by main.
• release approve posts the approval command to the pending release issue and advances the release.

The controlled release targets are account, zk-admin-server, and zk-websocket in zk-org-test.

Management Backend

admin auth login stores the verified token in the CLI config with 0600 permissions. The API origin defaults to https://tutti.sh; an admin.tutti.sh page URL is normalized automatically. For CI or temporary access, use NEXIGHT_ADMIN_TOKEN or TUTTI_ADMIN_TOKEN, and optionally NEXIGHT_ADMIN_URL or TUTTI_ADMIN_URL.

Read-only query commands accept --json for undecorated JSON output.

Tutti Computer runtime logs

The recommended command takes an exact Computer name or ID, or an owner username/email query, and an optional suspicious interval. An owner query must resolve to exactly one online Computer before recall starts. The command resolves the unique online Computer, selects the smallest backend range that covers the interval, creates the recall, waits for the device, downloads the result to a unique /tmp directory, and returns the artifact path:

nexight-devops admin computer logs "liyingdeMacBook-Pro.local" \
  --from "2026-09-01T10:30:00+08:00" \
  --to "2026-09-01T11:00:00+08:00" \
  --json

For a user-owned Computer, use the server-supported owner directory query:

nexight-devops admin computer logs \
  --owner-query "rv4no" \
  --from "2026-09-01T10:30:00+08:00" \
  --to "2026-09-01T11:00:00+08:00" \
  --json

--from and --to require an explicit timezone offset or Z; --to defaults to now. The backend supports fixed trailing ranges (1h, 3h, 1d, 3d, and 14d), so the downloaded archive can include additional logs between the suspicious interval and the current time. When no interval is available, use --range, which defaults to 1h:

nexight-devops admin computer logs <computer-name-or-id> --range 3h

The command writes elapsed-time progress lines to stderr while resolving the Computer, creating the task, waiting for device state changes, and downloading. --json keeps the final structured result on stdout, so Agents can observe progress without corrupting machine-readable output. The result never exposes the pre-signed storage URL or internal object key.

Use the lower-level task commands only when a recall needs to be created asynchronously, inspected, resumed, or downloaded to a specific path:

nexight-devops admin computer log-recall create --computer-id <computer-id> --range 1h
nexight-devops admin computer log-recall list --computer-id <computer-id>
nexight-devops admin computer log-recall get --computer-id <computer-id> --task-id <task-id>
nexight-devops admin computer log-recall download --computer-id <computer-id> --task-id <task-id>

Development

• Node.js 20+
• pnpm install
• pnpm lint
• pnpm typecheck
• pnpm dev -- --help
• pnpm test
• pnpm build

CLI publishing

The Publish CLI workflow checks pull requests and publishes @tutti-os/nexight-devops to npm after a successful push to main (including a merged pull request). It runs lint, type checking, tests, build, and CLI smoke checks before publishing. The publish job is serialized so two merges cannot choose the same npm version.

For the first publish, an npm user with write access to the @tutti-os scope must add a GitHub Actions repository secret named NPM_TOKEN. The token must allow direct publishing to that scope and unattended publishing when npm requires 2FA. The package is currently configured as public. Once the first version exists, the package owner can configure an npm trusted publisher for the tutti-lab/nexight-devops repository and publish-cli.yml workflow; the workflow already grants OIDC permission, so the token can then be removed.

package.json supplies the minimum release version. The first publish uses that version; later merges publish the next patch version above npm's current latest. To intentionally bump the minor or major version, raise package.json above the published version in the pull request. Re-running a workflow for a commit already published by this workflow skips publishing it again.

DataFinder OpenAPI

Run focused onboarding once. The CLI validates the credentials against the selected dashboard before saving them to the existing CLI config file, which is written with 0600 permissions.

nexight-devops onboard --set-mode datafinder
nexight-devops datafinder auth check

For temporary or CI use, these environment variables override stored values: DATAFINDER_AK, DATAFINDER_SK, DATAFINDER_PROJECT_ID, DATAFINDER_APP_ID, DATAFINDER_DASHBOARD_ID, DATAFINDER_BASE_URL, and DATAFINDER_TIMEZONE. DATAFINDER_PATH_MODE accepts project or app.

The default project path mode targets SaaS cloud-native projects. Select app during onboarding for legacy SaaS or private deployments that expose app-ID paths. The API origin must be a plain HTTPS origin without credentials, paths, query parameters, or fragments.

Dashboard and report queries

nexight-devops datafinder dashboard get
nexight-devops datafinder dashboard export --count 100 --output dashboard.json
nexight-devops datafinder report list
nexight-devops datafinder report get <report-id> --count 100

The two initial fixed internal queries resolve the default dashboard by stable report ID, with exact-name fallback for copied dashboards, and return the saved DataFinder query results:

nexight-devops datafinder query shared-agent-summary --count 100
nexight-devops datafinder query p2p-health --count 100

Generic JavaScript queries

query exec loads a local .js, .mjs, or .cjs module. The module must default-export a function and receives { client, config, args }. config contains only non-secret connection metadata. The client exposes getDashboard, listDashboardReports, getReportData, exportDashboard, analysis, and the lower-level request method.

export default async function query({ args, client, config }) {
  const [reportId, count = '1000'] = args;
  return {
    projectId: config.projectId,
    data: await client.getReportData(reportId, Number(count)),
  };
}

nexight-devops datafinder query exec ./query.mjs -- <report-id> 100

Query modules execute as trusted local Node.js code; this command is not a sandbox. Review generated modules before running them. Use --output <path> to write JSON with 0600 permissions instead of printing it.

Development demo

The standalone development demo reuses the production DataFinder client and exports the configured dashboard. Its defaults point to the Shared Agent 可靠性 dashboard.

pnpm demo:datafinder -- --credentials /path/to/AccessKey.txt

The credentials file must contain AccessKeyId and SecretAccessKey. You can instead set DATAFINDER_AK and DATAFINDER_SK. Run the demo with --help to override the project, app, dashboard, API origin, or per-report result limit.