Command Line Interface (CLI) Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Linux Archductor Command Line Interface (CLI) serves as the primary tool for automation, debugging, and fallback workflows within the project's Linux-native Git worktree ecosystem. While the project emphasizes a GUI-first design through its GTK application, the CLI provides parity with the backend logic, enabling users to manage repositories, workspaces, agent sessions, and pull requests directly from the terminal.
Sources: README.md:92-94, claude/CLAUDE.md:126-130
Architecture and Command Structure
The CLI is built using the clap crate for Rust, defining a hierarchical command structure that mirrors the internal domain model: Projects (Repositories), Workspaces, and Sessions. The CLI shares a core library (linux_archductor_core) with the GTK application to ensure consistent behavior across state management and process execution.
The diagram above illustrates the top-level command hierarchy of the linux-archductor CLI.
Sources: crates/cli/src/main.rs:27-106, README.md:16-30
Global Utilities
The CLI includes diagnostic and setup tools to ensure the local environment meets the requirements for parallel coding agents.
| Command | Description |
|---|---|
doctor | Runs a host diagnostic report, checking for dependencies like git, gh, sqlite, and openssh. |
import conductor | Imports repositories and workspaces from an existing macOS Conductor database. |
history | Lists or shows detailed messages from local chat history saved in SQLite. |
status | Provides a summary of all workspaces, their branch status, run states, and active sessions. |
Sources: crates/cli/src/main.rs:32-106, README.md:255-257, progress.md:188-193
Repository Management
Repositories (referred to as Projects in project documentation) are the root entities that own settings and workspaces. The repo subcommand manages the registration and configuration of these projects.
Settings Import/Export
The CLI allows for granular management of repository settings, which can be stored as shared (.archductor/settings.toml) or local (.archductor/settings.local.toml) layers.
# Export local overrides to a file
linux-archductor repo settings <name> export --local --output ./my-settings.toml
# Import shared settings from a file
linux-archductor repo settings <name> import ./shared-config.toml
Sources: crates/cli/src/main.rs:141-155, progress.md:161-164
Workspace Lifecycle
Workspaces are isolated Git worktrees created for specific tasks. The CLI provides comprehensive controls for creating workspaces from various sources and managing their disk footprint.
Workspace Creation
Workspaces can be seeded from manual branches or external issue trackers.
| Source Flag | Description |
|---|---|
--from-issue <num> | Fetches GitHub issue details to generate branch and workspace names. |
--from-pr <num> | Fetches a GitHub PR head ref and creates a worktree for review. |
--from-linear <id> | Uses a Linear issue ID to drive workspace creation (requires LINEAR_API_KEY). |
--prompt <text> | Generates a workspace and branch based on a task description. |
Sources: crates/cli/src/main.rs:158-173, progress.md:195-200, README.md:259-264
Directory Linking
For multi-repository workflows, the CLI manages symlinks under .context/linked-directories/ to expose related workspaces to agent sessions.
Sources: crates/cli/src/main.rs:194-202, progress.md:130-136
Session and Agent Control
The CLI manages PTY-backed harnesses for different agent types, including Codex, Claude, and Cursor.
The sequence above shows the logic for starting agent sessions, specifically noting the diversion for Codex which uses the archcar internal protocol.
Sources: crates/cli/src/main.rs:564-583, progress.md:86-90
Interactive Attachment
The session attach command allows users to join the PTY of a running session. The CLI resolves the terminal device path via /proc/<pid>/fd/0 to enable direct interaction.
Sources: crates/cli/src/main.rs:647-657, crates/cli/src/main.rs:693-703
Pull Request Integration
The CLI integrates with the GitHub CLI (gh) to manage the PR lifecycle without leaving the workspace context.
Readiness Summaries
The pr summary command fetches deployment rollups, check statuses, and review threads. It can output a raw text summary or an agent_prompt format designed to be staged into an agent session for automated fixing of CI failures.
Sources: crates/cli/src/main.rs:241-245, progress.md:213-220
Review Thread Resolution
The CLI can resolve or reopen GitHub review threads using GraphQL via the gh backend.
linux-archductor pr resolve-thread <workspace> <thread_id>
Sources: crates/cli/src/main.rs:246-253, progress.md:227-229
Conclusion
The Linux Archductor CLI provides a robust, text-based interface for managing the entire agentic development workflow. By offering deep integration with Git worktrees, GitHub, and PTY-backed agent harnesses, it ensures that project management and agent orchestration remain accessible and scriptable for power users and CI/CD pipelines alike.