Command: status
Relevant source files
The following files were used as context for generating this wiki page:
The status command is the primary diagnostic and entry-point tool within the cxs CLI. Its purpose is to report the execution context, source inventory, SQLite index state, and coverage status without modifying any data. It is a read-only command that provides the necessary metadata for users and agents to decide whether a synchronization (sync) is required before performing content-based queries.
Sources: AGENTS.md:15-18, skill-packages/cxs/references/cli-surface.md:13-15
Core Functionality and Architecture
The status command serves as the first step in the standard cxs workflow: status -> ensure selector coverage -> find/list -> read-range/read-page. It orchestrates information from two main locations: the local file system (raw Codex session metadata) and the local SQLite database (the index).
Information Sources
- Execution Context: Reports the current working directory, the root directory for sessions, and the path to the database.
- Source Inventory: Scans raw session metadata to report the total number of files, the date range of these files, and groups them by their original working directory (
cwd). - Index State: Checks if the SQLite database exists and reports the number of indexed sessions and messages.
- Coverage Status: Lists previously completed synchronization records (selectors) and their current freshness (fresh vs. stale).
Sources: src/format.ts:133-157, skill-packages/cxs/references/cli-surface.md:17-18, AGENTS.md:11
Architectural Data Flow
The following diagram illustrates how the status command aggregates data without performing write operations:
The diagram shows that the status command acts as a read-only aggregator between the local session files and the indexed database.
Sources: AGENTS.md:16-18, src/status.test.ts:43-48
Detailed Logic: Selector Coverage
A critical feature of the status command is its ability to perform targeted coverage checks using the --selector flag. When a selector is provided, the command determines if the specific subset of data is ready for querying or requires a sync.
Recommended Actions
Based on the provided selector, the command calculates a recommendedAction:
query: The requested range has fresh, complete coverage in the index.sync: Coverage is either missing or "stale" (the source files have changed since the last sync).
Sources: skill-packages/cxs/references/cli-surface.md:21-23, src/status.test.ts:77-108
Freshness Logic
Freshness is determined by comparing the current source snapshot's fingerprint with the fingerprint recorded in the database's coverage table.
This flowchart depicts the decision logic used to determine if the index is up-to-date for a specific project or date range.
Sources: src/status.test.ts:63-108, skill-packages/cxs/references/cli-surface.md:21-23
Technical Specifications
Command Options
| Option | Description |
|---|---|
--selector <json> | Checks the freshness and completeness of a specific range (all, cwd, date_range). |
--json | Returns the status information as a structured JSON object. |
--root <path> | Overrides the default Codex sessions directory. |
--db <path> | Overrides the default database location. |
Sources: skill-packages/cxs/references/cli-surface.md:17-20, src/cli.test.ts:43-51
Output Structure (JSON)
When run with the --json flag, the command returns a StatusSummary object.
// Derived from StatusSummary type
{
context: {
cwd: string;
root: string;
dbPath: string;
},
sourceInventory: {
totalFiles: number;
pathDateRange: { from: string; to: string };
cwdGroups: Array<{ cwd: string; fileCount: number }>;
},
index: {
exists: boolean;
sessionCount: number;
messageCount: number;
},
coverage: CoverageInventoryStatus[],
requestedCoverage?: RequestedCoverageStatus // Only if --selector is used
}
Sources: skill-packages/cxs/references/json-schema.md:65-83, src/format.ts:133-157
Implementation Details
The status information is formatted for the console using the printStatus function, which utilizes the chalk library for highlighted output.
// Example from src/format.ts:133-157
export function printStatus(status: StatusSummary): void {
console.log(chalk.bold.cyan("cxs status"));
console.log(`cwd: ${status.context.cwd}`);
console.log(`root: ${status.context.root}`);
console.log(`db_path: ${status.context.dbPath}`);
console.log(`index_exists: ${status.index.exists}`);
if (status.requestedCoverage) {
console.log(`requested_coverage: ${status.requestedCoverage.freshness}`);
console.log(`recommended_action: ${status.requestedCoverage.recommendedAction}`);
}
}
Sources: src/format.ts:133-157
Summary
The status command is an essential tool for maintaining visibility into the cxs indexing state. By providing a detailed "source inventory" and "coverage freshness" report, it prevents unnecessary indexing operations and ensures that queries are performed against accurate and fresh data. Developers and agents should always use status --selector to check the recommendedAction before attempting a sync or find operation.