feat: add ory use workspace

[alnr]

Closes #406

Problem

The documentation advertises ory use workspace <id> for setting the default workspace, and ory auth prints a SELECTED WORKSPACE field — but the subcommand was never registered. ory use offered only project, so the workspace had to be passed via --workspace on every single invocation.

Fix

The config already carried a selected_workspace field and CommandHelper.SelectWorkspace already persisted it, so this is mostly wiring. The new subcommand mirrors ory use project: with an argument it resolves the given ID or (partial) name and stores it; without one it reports the current default.

One bug found in review and fixed: the no-argument form was calling SelectWorkspace too, so merely reading the current default could silently rewrite it. With ORY_WORKSPACE=B ory use workspace, determineWorkspaceID prefers the env var over the config, so the "read-only" form would persist B over the stored value. It now only writes when an argument was actually given.

Also adds the workspaces alias, which every other workspace subcommand accepts — without it ory use workspaces matched no subcommand, printed the use help and exited 0, so a script relying on the exit code would carry on as if the workspace had been set.

Tests

TestUseWorkspace runs entirely against a config file, so unlike its cmd/cloudx neighbours it needs no Ory Network access — selecting a known workspace ID never hits the API. It covers printing the default, the --format json shape the command's own example advertises, persisting a new default, the not-set error, and the read-only regression above (verified to fail against the pre-fix code).

The persist test also asserts the access token survives the config rewrite: SelectWorkspace re-encodes the whole config with O_TRUNC, so a partially populated struct would silently log the user out.

Known limitations, deliberately not addressed here

These all apply equally to the existing ory use project and live in unchanged shared code, so they belong in a separate change rather than being special-cased for workspaces:

• A well-formed but wrong UUID is persisted without validation and reports success, because determineWorkspaceID takes the uuid.FromString fast path and never contacts the API. Later workspace-scoped commands then fail with an opaque 403/404.
• With ORY_PROJECT_API_KEY exported, ory use workspace <id> fails with "project API key is set but workspace is also set" — the user has to unset an unrelated env var.
• A set-but-empty ORY_WORKSPACE suppresses the config fallback, so the command reports "no workspace was specified" even with a default stored.
• Switching workspaces leaves selected_project pointing at a project in the old workspace. The test asserts the project is not cleared, so this is a conscious choice — flagged in case you would rather it were.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JYzGVwAKQ4ormxRHZg1eDu

Summary by CodeRabbit

• New Features

  • Added cloudx use workspace [id] to select and display the active workspace.
  • Supports quiet and JSON output formats.
  • Preserves existing project and authentication settings when changing workspaces.
  • Reports a clear error when no workspace is configured.

• Tests

  • Added coverage for workspace selection, output formats, configuration persistence, overrides, and missing workspace settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds the ory use workspace [id] command, including workspace resolution, optional persistence, formatted output, missing-workspace errors, command registration, and focused CLI tests.

Changes

Workspace selection

Layer / File(s)	Summary
Workspace errors and output contract cmd/cloudx/client/command_helper.go, cmd/cloudx/workspace/output.go	Adds ErrWorkspaceNotSet and a table row that renders workspace IDs in default and JSON formats.
Workspace command wiring and execution cmd/cloudx/use.go, cmd/cloudx/workspace/use.go	Registers use workspace, resolves explicit or configured workspace IDs, persists explicit selections, and prints the selected workspace.
Workspace command validation cmd/cloudx/workspace/use_test.go	Tests quiet and JSON output, context overrides, configuration persistence, preservation of project and token settings, and missing-workspace errors.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant WorkspaceCommand
  participant CommandHelper
  participant Config
  participant Output
  CLI->>WorkspaceCommand: invoke use workspace [id]
  WorkspaceCommand->>CommandHelper: resolve workspace ID
  CommandHelper->>Config: read or persist workspace selection
  WorkspaceCommand->>Output: print selected workspace

Loading

Possibly related PRs

• ory/cli#425 — Modifies workspace-selection logic in command_helper.go, which supports the new workspace command.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding the ory use workspace command.
Description check	✅ Passed	The description covers the problem, fix, tests, and related issue; it is mostly complete despite missing checklist and further comments sections.
Linked Issues check	✅ Passed	The changes satisfy #406 by registering ory use workspace, preserving selection behavior, and adding tests for the documented cases.
Out of Scope Changes check	✅ Passed	The added alias, read-only protection, and tests are directly related to the workspace subcommand and do not appear out of scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/406-use-workspace

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

cmd/cloudx/workspace/use_test.go (1)

53-112: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the documented workspaces alias.

All cases invoke workspace directly, so a regression in the new workspaces alias would go undetected. Add one alias invocation to the existing output or persistence test.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cmd/cloudx/workspace/use_test.go` around lines 53 - 112, Extend the existing
workspace command tests to invoke the documented workspaces alias in at least
one output or persistence scenario. Update a suitable case around the existing
test subcases so it verifies the alias produces the same expected result as
workspace, while preserving the current coverage for the canonical command.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@cmd/cloudx/workspace/use_test.go`:
- Around line 53-112: Extend the existing workspace command tests to invoke the
documented workspaces alias in at least one output or persistence scenario.
Update a suitable case around the existing test subcases so it verifies the
alias produces the same expected result as workspace, while preserving the
current coverage for the canonical command.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cfe7577a-d0af-4c3c-87a5-22c403e4f5fa

📥 Commits

Reviewing files that changed from the base of the PR and between 6b55b72 and 126917f.

📒 Files selected for processing (5)

• cmd/cloudx/client/command_helper.go
• cmd/cloudx/use.go
• cmd/cloudx/workspace/output.go
• cmd/cloudx/workspace/use.go
• cmd/cloudx/workspace/use_test.go