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.

• Org selection is resolved in this order: --org <slug> -> VELEN_ORG -> the nearest workspace .velen.config.json -> the selected profile's stored active_org. Org-scoped commands fail explicitly when none of those sources selects an org.

• Workspace discovery starts in the current directory, walks upward, uses the nearest .velen.config.json, and stops after checking the Git root. A nested workspace config can therefore override the repository-root config.

• Workspace config is versioned JSON:

  {
    "version": 1,
    "org": "acme"
  }

• velen org use <org> persists the user default in config.toml. velen org use <org> --workspace writes .velen.config.json at the current Git workspace root. velen org current reports the selected source and the workspace config path when applicable.

• A malformed workspace config is reported with its path instead of being ignored. Explicit --org and VELEN_ORG candidates short-circuit workspace loading, and commands that do not use org context (for example auth login) do not inspect workspace config.

• 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 user-default active_org for the selected profile. Workspace config is repository state and is not removed by logout.

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.