> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_01/session_03_cli_lifecycle_parity.md). # Session 03: CLI Lifecycle Parity **Session ID**: `phase01-session03-cli-lifecycle-parity` **Packages**: apps/cli, apps/hooks **Status**: Not Started **Estimated Tasks**: \~16-22 **Estimated Duration**: 2-4 hours *** ## Objective Bring the current CLI setup and local lifecycle commands up to the retained original affordance level for install, status, doctor, launch, browser open, stop, uninstall, port, PID, and workspace-root behavior. *** ## Scope ### In Scope (MVP) * Compare current `apps/cli` command surface against original CLI and launcher sources. * Preserve and test hook install, backup, merge, and uninstall behavior. * Add or document start/open/stop/status/doctor behavior that fits the current workspace. * Ensure PID, port, and workspace-root behavior is deterministic. * Apply atomic writes for user-owned settings and hook configuration where needed. * Update CLI README and root usage docs for supported commands. ### Out of Scope * Publishing an npm package. * Hosted auth or cloud account setup. * Non-Claude provider launch beyond documented compatibility hooks. *** ## Prerequisites * [ ] Current `apps/cli` commands and package manifest are reviewed. * [ ] Current hook install and uninstall behavior is covered by fixtures or can be fixture-tested. * [ ] The local server launch command path is clear from package scripts. *** ## Deliverables 1. CLI lifecycle behavior matching retained product requirements. 2. Filesystem fixture tests for install, backup, merge, uninstall, PID, port, and workspace behavior. 3. README updates for real local workflow commands. *** ## EXAMPLES Implementation Sources | Source | Feature / Contract | Tests Required | Documentation Owner | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `EXAMPLES/1st-pass-artifacts/bundled-README.md` | Original install, launch, status, doctor, open, stop, uninstall, and workspace workflow | CLI integration tests and README parity checklist | `README.md`, `apps/cli/README_cli.md` | | `EXAMPLES/1st-pass-artifacts/bundled-package.json` | Original bin name, package files, scripts, dependencies, and Node engine expectations | Package manifest checks and current-workspace command documentation | `README.md`, `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/bin/agentcraft.js` | Executable entry point and command dispatch expectations | Bin smoke tests for current executable entry | `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/lib/cli.js` | Original command semantics and user-facing output expectations | CLI command tests with mocked process and filesystem | `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/lib/installer.js` | Hook settings backup, merge, managed-entry uninstall, and recovery behavior | Filesystem fixture tests for install and uninstall without clobbering user hooks | `apps/cli/README_cli.md`, `apps/hooks/README_hooks.md` | | `EXAMPLES/package-0.4.1/lib/launcher.js` | Start, daemon, browser open, PID, port, and workspace-root behavior | Launcher tests for port selection, PID file handling, status, stop, and workspace root | `README.md`, `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/lib/config.js` | Local config directory, auth token storage, server PID, server env, and project-dir persistence | Config fixture tests for atomic writes, permissions, PID lifecycle, and secret handling | `apps/cli/README_cli.md`, `docs/privacy-and-security.md` | *** ## Success Criteria * [ ] CLI commands preserve user hook settings and remove only FactionOS-managed entries. * [ ] Status and doctor outputs diagnose server, hook, port, PID, and workspace state. * [ ] Start/open/stop behavior is either implemented or explicitly documented with current equivalent commands. * [ ] User-owned settings writes use an atomic temp-write-plus-rename pattern where practical. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_01/session_03_cli_lifecycle_parity.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.