NAME
workspace - private tmux workspace helper for Developer Dashboard
SYNOPSIS
dashboard workspace <workspace-ref>
dashboard workspace -c <workspace-ref>
dashboard workspace <workspace-ref> -c
dashboard workspace -c <path-alias> --docker
dashboard workspace <path-alias> -c -dDESCRIPTION
This private helper is staged under ~/.developer-dashboard/cli/dd/ so the main dashboard command can keep workspace-session behaviour available without installing a generic executable into the user's global PATH.
PURPOSE
This staged helper exposes dashboard workspace, the command that creates or reuses a tmux session for one workspace and then attaches the terminal to it. It is the shell-facing entrypoint for the workspace-session workflow.
WHY IT EXISTS
It exists because workspace-session behavior is a built-in convenience feature, but the public switchboard should stay thin while the workspace module owns tmux session naming, layered env seeding, and create-vs-attach logic.
WHEN TO USE
Use this file when changing the dashboard workspace CLI contract, the staged helper handoff, or the examples contributors use to understand explicit workspace selection and session environment refresh behavior.
HOW TO USE
Users run dashboard workspace <workspace-ref> or set WORKSPACE_REF and run dashboard workspace. The staged helper forwards the request into the private runtime, which loads Developer::Dashboard::CLI::Ticket, resolves the workspace name, seeds WORKSPACE_REF, TICKET_REF, B, and OB in the tmux session environment, refreshes layered plain-directory .env values from the highest ancestor down to the current directory, creates a detached Code1 window when the session does not exist yet, and then attaches to that session.
Adding -c before or after the workspace name changes directory first: when the workspace name is registered in the dashboard paths inventory (the same registered names the shell cdr helper resolves), including configured path aliases and skill-qualified methods from a skill's lib/Folder.pm, the helper changes into that registered directory before planning the session. Dotted skill names remain qualified at every nesting depth, such as parent.child.work. Configured aliases take precedence when a configured name collides with a Folder.pm method. The tmux session and its layered .env refresh both start from the resolved directory. When the name is not a registered dashboard path, -c fails with an explicit error instead of silently starting the workspace from the wrong directory.
Use -d or --docker together with -c and a registered path alias to run the workspace inside the Compose service named workspace. The helper first changes into the alias target and runs d2 docker compose up -d --build workspace. If that fails, it stops and asks the user to configure the service; it does not run any in-container commands. On success it runs d2 docker compose exec workspace d2 path add <alias> /workspace, then d2 docker compose exec workspace d2 workspace <alias> -c. The last command starts the normal tmux workspace inside the container. Docker mode uses argument-list process execution rather than a shell. Without -d or --docker, the regular local tmux workspace flow is unchanged. The Compose service must bind-mount the alias target at /workspace and stay running so both in-container commands can execute.
WHAT USES IT
It is used by workspace-session workflows in the shell, by prompt integrations that rely on consistent workspace environment variables, and by regression tests that verify explicit workspace selection, env refresh, and environment fallback.
EXAMPLES
dashboard workspace
dashboard workspace DD-123
WORKSPACE_REF=DD-123 dashboard workspace
dashboard workspace feature-branch-42
dashboard workspace -c foobar
dashboard workspace foobar -c
dashboard workspace -c foobar --docker
dashboard workspace foobar -c -d