Choose the GUI or CLI

Day Shift’s GUI and CLI work with the same project files and lifecycle evidence. You can plan in the browser, implement with your preferred coding agent, and inspect or continue the work from a terminal. A browser, inference provider, and running GUI server are optional for CLI workflows.

This guide describes the current repository build. Check day-shift --version, day-shift about, and day-shift serve --help against the release you installed. Older archives may contain only the CLI; the presence of a guide does not add a feature to an older executable.

Start in the browser

Follow Installation, then enter the project directory and run:

day-shift serve --open

The command runs the project server in the foreground and opens its local GUI. Without --open, open the printed GUI address yourself. Use day-shift serve --project <project-directory> to select another project or --port <port> to require an exact loopback port. Keep the terminal running; Ctrl+C stops the server and returns the terminal on a new line. Closing the browser does not stop it. In an interactive serving terminal, Ctrl+E prints retained diagnostics from that runtime session and preserves end-of-line editing. Ctrl+X followed by Ctrl+K opens a clear prompt; type CLEAR and press Enter to delete retained project diagnostics, or enter another answer to cancel. These shortcuts require an interactive terminal. See caught GUI failures for the browser controls and retention policy.

For a fresh project, read the setup screen and choose its initialization action when you are ready to create the workspace. An existing workspace opens its current documents. You can instead initialize entirely from the terminal using Workspace initialization.

Open Project Brief to describe the overall project, Specs to define a change, and Planning to choose its workflow and prepare tasks. Academy explains the interface and offers examples. Configure a provider in Settings → AI providers when you want chat assistance. Viewing and editing project documents does not require an AI response. Continue with GUI planning workflows for review and handoff.

The printed connection URL belongs to one project runtime. After a restart, open the new URL or choose Open the current project. Preserve unsaved text before reloading. Treat verbose startup output and JSON connection details as private: they include session credentials. This server binds to loopback; it is not a hosted multi-user service.

Continue entirely from the terminal

Start with the complete Basic task walkthrough for one independent task, Structured feature workflow for specification-backed work, or Governed workflow for staged review. These paths include creation, readiness, attempts, validation, summaries, and closeout without browser steps.

For existing work, inspect before choosing a write:

day-shift work current --session default --format json
day-shift work candidates --format json --detail compact
day-shift planning next-action --artifact <existing-artifact> --format json
day-shift doctor --artifact <existing-planning-artifact> --format json

Replace angle-bracket paths with existing project artifacts. A suggested next action is guidance; use its documented inputs and authorization before executing it. Give your coding agent the workspace’s .day-shift/agents.md and the selected task lifecycle guide. See Agent orientation for automation-specific instructions.

Find the corresponding workflow

The CLI column names command families or reference paths, not complete copy-and-run commands. Use day-shift <command> --help or day-shift commands describe "<command path>" --format json for exact inputs in your installed version.

Goal	Current GUI	Terminal workflow and durable documentation
Initialize and diagnose	Project setup, health findings, Settings	init, doctor, config; setup and health
Describe and plan work	Project Brief, Specs, Planning, next-layer previews	spec, work create, work task create, Governed layer commands; intake to implementation
Choose current work	Work queue and current work in Planning	work candidates, work current, work select, work clear; current work. Use the same selection session in both interfaces. Browsing alone does not change selection.
Find gaps and the next step	Next steps and review, Actions	planning next-action, planning gap-report, selected-artifact review; core command reference
Prepare and complete an attempt	Task attempt lifecycle and Task recovery	task readiness-review, readiness-authorize, attempt-open, baseline, implementation-complete, and recovery commands; lifecycle records
Implement and validate	External-agent handoff and returned evidence; supported syntax checks, Node tests and package validation scripts; separate completed-task follow-up checks	Source implementation stays with your editor or agent. Use task validation-set or task validation-record for supported declared tests/builds; handoff and return
Review and close work	Eligible lifecycle actions and reconciliation controls	Summary review, task disposition/close, reconciliation, project review, work close; evidence review
Inspect prior runs	Run history, Metrics and comparison	resume run status, resume, explain, friction-report, compare; resume and evidence
Repair trace references	Trace-link inspection, disposition preview and explicit apply	validation links-check, link disposition; trace recovery. Migration repairs canonical trace fields; it does not rewrite arbitrary prose links.
Change project configuration	Settings → Project, Day Shift project settings	config get, config inventory, config set; configuration layers
Tune runtime capacity	Settings → Performance and limits, environment presets and individual overrides	Local performance.* configuration; limits and presets
Inspect caught GUI failures	Settings → Diagnostics, grouped session history, copy/export and confirmed clear	Ctrl+E in the interactive serving terminal; diagnostics and retention. doctor inspects health separately.
Edit instructions and maintain defaults	Policy packs, Prompts, Settings → Maintenance	Edit workspace-owned Markdown; use prompt, template, templates, workspace upgrade; customization and upgrades
Prepare delivery and capture feedback	Delivery documents and external records; Feedback documents and intake	Saved handoff/feedback Markdown can be read and edited outside the GUI. These runtime flows have no equivalent top-level CLI command family. Use the delivery and feedback guides for file ownership; register follow-up specifications with spec.
Automate or repair advanced state	Some operations intentionally route to CLI guidance	Protocol controls, lifecycle capture/packing, contract revision, validation recovery, migration, release preparation, shell integration; automation, operations, transaction recovery

An unavailable GUI action can reflect missing evidence, insufficient permissions, an unsupported selection, or missing runtime support. A CLI command does not bypass those preconditions. Use the CLI when the operation is supported there, and preserve the same review and write boundaries.

What the docs provide beyond the interface

Keep these references available even when most work happens in the GUI:

• Workflow choice, artifact ownership, readiness, evidence profiles, and acceptance semantics in Concepts.
• Complete terminal procedures, exact flags, JSON contracts, and examples for agents, scripts, and CI in Workflows and Reference.
• Recovery when the browser or server cannot start, state is stale, or a transaction is incomplete in Troubleshooting.
• Configuration precedence, prompt/template ownership, migration, version selection, and licensing procedures that must remain accessible during maintenance.
• Provider disclosure, external-agent responsibilities, evidence provenance, and compatibility limits.

Academy and contextual help explain controls where you use them. The docs explain the full process and its contracts. Neither a chat answer nor a completed GUI action substitutes for the required implementation evidence, review, or external delivery result.