ATMOS Command Line Tool
Relevant source files
The following files were used as context for generating this wiki page:
The ATMOS Command Line Tool (CLI) serves as the primary terminal-based interface for interacting with the ATMOS ecosystem. It is designed to empower developers and AI agents to manage projects, automate documentation workflows, and orchestrate system tasks directly from the shell. The CLI is a core component of the "Layered Architecture" of the project, providing a task-oriented entry point for component-level work.
The tool is built using Rust, ensuring high performance and safety while managing complex operations like codebase research and metadata collection. It acts as the execution engine for specialized "skills," such as the Project Wiki generation system, allowing users to invoke sophisticated research-grade agents via simple command-line arguments.
Sources: apps/cli/Cargo.toml, DOCUMENTATION.md:9-25, skills/project-wiki/README.md:1-10
Architecture and Integration
The ATMOS CLI operates as a bridge between the user's terminal and the internal logic of the project's various modules and applications. It is integrated into the web-based frontend via a terminal orchestration layer, allowing the web interface to trigger CLI commands programmatically.
System Flow Overview
The following diagram illustrates how the CLI fits into the broader system architecture, specifically in the context of documentation generation:
The CLI is responsible for initializing terminal tabs and dispatching commands that trigger specific agent presets. For instance, it handles the execution of tools like Claude Code, Codex, or Aider to perform deep codebase research.
Sources: specs/tech/project-wiki.md:46-55, skills/project-wiki/SKILL.md:40-60
Key Components and Commands
The CLI is structured to handle various specialized tasks through a command-based interface. One of its primary responsibilities is managing the "Project Wiki" workflow.
Core CLI Features
| Component | Description |
|---|---|
| Agent Selector | Allows choosing between different AI engines (Claude, Codex, Aider). |
| Metadata Collector | Script-driven component that extracts Git logs and PR/Issue data. |
| Validation Suite | Python and Shell-based scripts used to verify generated artifacts. |
| Terminal Orchestration | Managed interface for creating and running terminal sessions. |
Sources: skills/project-wiki/SKILL.md:15-30, specs/tech/project-wiki.md:104-120
Document Generation Workflow
The CLI orchestrates a multi-step process for generating documentation. This process involves collecting metadata, researching the codebase, and validating the final output.
Technical Implementation (Rust)
The CLI is implemented as a Rust workspace member. Its configuration and dependencies are managed via Cargo.toml.
Dependencies
The tool leverages the Rust ecosystem for robust terminal interactions and filesystem management. Key aspects of the implementation include:
- Workspace Integration: Part of the
appsdirectory, allowing it to share packages with other project components. - Performance: Utilizes Rust's safety and speed for parsing large metadata files and traversing directory structures during research phases.
Sources: apps/cli/Cargo.toml:1-10, apps/cli/AGENTS.md:1-5
Command Presets
The CLI uses controlled presets to ensure command safety. It avoids raw shell execution in favor of escaped and interpolated strings for specific agent tools.
// Logical representation of command building
// Sources: [specs/tech/project-wiki.md:112-117]
const AGENT_COMMANDS = {
claude: (prompt) => `claude ${shellQuote(prompt)}`,
codex: (prompt) => `codex ${shellQuote(prompt)}`,
aider: (prompt) => `aider --message ${shellQuote(prompt)}`,
};
Documentation and Metadata Management
The CLI provides the infrastructure for managing "research-grade" documentation. This includes the ability to generate a _catalog.json file that defines the hierarchical structure of the project wiki.
Metadata Collection
The CLI triggers scripts to collect Git metadata, which is stored in .atmos/wiki/_metadata/. This metadata includes:
- commit_graph.txt: Visual representation of the Git log.
- commit_details.txt: Full logs with file statistics.
- contributors.txt: Git shortlog of project contributors.
Sources: skills/project-wiki/SKILL.md:65-75, DOCUMENTATION.md:145-160
Summary
The ATMOS Command Line Tool is a critical utility for technical research and documentation automation within the ATMOS project. By bridging high-level AI agents with low-level codebase metadata, it enables the creation of deep, architecture-focused wikis that go beyond simple README summaries. Its integration into the project's layered documentation strategy ensures that both human developers and AI agents have a consistent, task-oriented interface for system management.
Sources: DOCUMENTATION.md:1-15, skills/project-wiki/README.md:10-25