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.
• Named profiles use ${XDG_CONFIG_HOME:-~/.config}/velen/profiles/<profile>/config.toml on Unix-like systems and %APPDATA%\\velen\\profiles\\<profile>\\config.toml on Windows.
• Select a profile with --profile <profile>, VELEN_PROFILE, or the persisted default from velen profile switch <profile>; --profile takes precedence over VELEN_PROFILE, which takes precedence over the persisted default. The default profile keeps using the legacy flat paths above.
• List local profiles with velen profile list.
• The current persisted keys are active_org and request_timeout_sec; the built-in request timeout defaults to 180 seconds.
• 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.
• The CLI generates an invocation-scoped request ID when --request-id is not provided, attaches it to outbound HTTP requests, and can report it on transport errors even when no response body is received.
• Prefer the built-in request timeout for normal commands. Use --timeout <sec> only when an invocation intentionally needs a shorter or longer request window.
• velen auth logout clears both the stored auth session and the stored active_org for the selected profile, 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.
• Named profiles use ${XDG_CONFIG_HOME:-~/.config}/velen/profiles/<profile>/auth.json on Unix-like systems and %APPDATA%\\velen\\profiles\\<profile>\\auth.json on Windows.
• 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.
• VELEN_ACCESS_TOKEN remains invocation-only and takes precedence over the selected profile's stored auth session without implicitly writing to it.

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
• velen update updates the globally installed Velen binary and Velen CLI agent skill.
• velen skill add installs or updates the Velen CLI agent skill globally.
• 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.
• Only temporary release/... branches should change apps/cli/Cargo.toml and apps/cli/Cargo.lock to the real release version before tagging.
• After the release is tagged, close or delete that temporary release branch/PR so origin/main stays at 0.0.0.
• 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.