Jeden/Docs

CLI command

jeden workspace

Inspect, validate, adopt or forget an existing local repository as Jeden's default workspace.

Exact invocation#

Shell
jeden workspace [status|discover [path]|adopt <path>|forget] [--json]

Inputs and options#

  • No action defaults to status. discover accepts an optional existing path and otherwise inspects the current directory. adopt requires a path.
  • A relative path is resolved from the invocation directory; --json returns the same operation report as a JSON object.
  • The supported sources are an existing readable directory and a Git working tree detected by an existing .git directory or worktree file in that path or an ancestor. Jeden session history is associated through each canonical state.json cwd; it is not re-imported.

Output and state effect#

discover validates without writing. adopt validates the complete source first, then atomically stores its canonical absolute path as workspace.defaultPath in ~/.jeden/config.yml. A later interactive, run, or pursue task uses that workspace unless --cwd is explicit; adoption from a running terminal first-use or setup screen also rebases that session before its next agent turn. The result names the accepted path, source kind, repository root, existing sessions accepted or unreadable, and imported/unchanged/conflicting/rejected counts. It never copies, cleans, resets, or writes the repository or its session ledgers.

Refusals and boundaries#

  • The functionality is jeden.workspace; jeden errors show jeden.workspace prints every cause with its test (tests/workspace/command.mjs). Read before any directory, each exit 2: verb-unknown, path-missing (adopt requires the path of a directory, and the command line ends before one), argument-unexpected (a word after the request) and path-climbs (a workspace path must not contain `..`, observed: the path as resolved).
  • Examining the directory, each exit 1 and before the selection changes: directory-missing (workspace &lt;path&gt; is not an existing readable directory), not-a-directory, directory-unreadable (this user cannot list it), git-unexaminable (a .git that cannot be examined, such as a symbolic link loop), sessions-unreadable (the session root cannot be listed) and the causes of jeden.config.read for its .jeden/config.json; writing the selection has the causes of jeden.config.write. adopted-not-text refuses a workspace.defaultPath that is not a string, and report-unencodable a --json report of a path that is not UTF-8.
  • If a previously adopted path is unavailable, implicit task startup refuses with that directory's cause and the line context: the workspace adopted in the user configuration is unavailable; --cwd &lt;path&gt; runs the command in another, and `jeden workspace forget` drops it, instead of silently changing workspace.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: &lt;operation&gt;.&lt;cause&gt;, and jeden errors show &lt;operation&gt; lists every cause of that functionality.