velen

Rust CLI workspace for velen and the companion CLI API contract.

Key references:

• Human-oriented protocol and workflow spec: docs/SPEC.md
• Split OpenAPI source: ../../packages/cli-contract/openapi/source/cli.openapi.yaml
• Generated JSON API contract: ../../packages/cli-contract/openapi/generated/cli.openapi.json

Runtime config:

• On Unix-like systems, the user config file is ${XDG_CONFIG_HOME:-~/.config}/velen/config.toml.
• On Windows, the user config file is %APPDATA%\\velen\\config.toml.
• The current persisted keys are active_org and request_timeout_sec.
• Runtime config is resolved in this order: built-in defaults -> user config file -> internal typed runtime overrides.
• velen org use <org> persists active_org. Passing --org <org> for a command takes precedence over the stored active_org value for that invocation.
• velen auth logout clears both the stored auth session and the stored active_org, so later org-scoped commands fail explicitly until a new org is selected.

Credential storage:

• On Unix-like systems, the CLI persists the full auth session blob to ${XDG_CONFIG_HOME:-~/.config}/velen/auth.json.
• On Windows, the CLI persists the full auth session blob to %APPDATA%\\velen\\auth.json.
• auth.json stores the user identity, bearer token, session timing metadata, and the last refresh timestamp.
• Authenticated commands now run an explicit auth-session lifecycle before building an authenticated API client: load auth.json on startup -> call the CLI session refresh contract -> persist the returned token and timing metadata.

Version cache:

• Release builds refresh ${XDG_CONFIG_HOME:-~/.config}/velen/version.json on Unix-like systems and %APPDATA%\\velen\\version.json on Windows as a cached latest-version record sourced from the npm dist-tags for @wordbricks/velen.
• The cache format mirrors Codex: latest_version, last_checked_at, and dismissed_version.

Install:

• bun install -g @wordbricks/velen
• bunx @wordbricks/velen --help
• npx @wordbricks/velen --help
• Linux npm installs ship musl-linked binaries so the CLI runs on both glibc and musl-based distributions, including Alpine.
• Windows npm installs ship both x64 and arm64 platform binaries.

Release:

• Keep apps/cli/package.json at 0.0.0-dev.
• Keep apps/cli/Cargo.toml and apps/cli/Cargo.lock at 0.0.0 on normal development commits.
• Before tagging a release, update apps/cli/Cargo.toml and apps/cli/Cargo.lock to the real release version on the tagged commit.
• After the release commit, return the Rust workspace version metadata to 0.0.0 on the next development commit.
• Configure npm trusted publishing for @wordbricks/velen with GitHub Actions using the workflow filename cli-release.yml.
• Push a tag like cli-v0.1.0 or cli-v0.1.0-alpha.1.
• The cli-release workflow validates cli-v<version> against apps/cli/Cargo.toml, builds GNU and musl Linux binaries plus the other platform binaries, stages npm tarballs, creates a GitHub release, and publishes them to npm with npm publish --provenance.
• Linux npm platform tarballs are staged from musl artifacts for the broadest runtime compatibility.