CLI Commands
Relevant source files
The following files were used as context for generating this wiki page:
The Serena Command Line Interface (CLI) serves as the primary gateway for users and AI agents to initialize, configure, and manage the Serena environment. It provides a structured set of commands for project management, memory manipulation, and starting the Model Context Protocol (MCP) server. The CLI is built using the click library and employs an auto-registering group architecture to organize complex subcommands into logical modules.
Sources: src/serena/cli.py:58-64, README.md:160-170
Architecture and Command Structure
The CLI is organized into a hierarchical structure where the TopLevelCommands class acts as the root group. Various specialized command groups are registered to this root to handle different aspects of the system.
The diagram above illustrates the hierarchical organization of Serena's CLI commands, branching from the root serena entry point into functional sub-modules.
Sources: src/serena/cli.py:105-1120
Core Initialization Commands
These commands are used during the initial setup of Serena on a local system.
| Command | Description | Key Options |
|---|---|---|
init | Initializes the global configuration file. | --language-backend (-b) |
setup | Registers Serena as an MCP server for specific clients (e.g., Claude Code). | client (Argument) |
start-mcp-server | Launches the MCP server to interface with AI clients. | --port, --transport, --project |
Sources: src/serena/cli.py:113-255
Project Management
The project subcommand group handles the lifecycle of a Serena-enabled codebase. This includes auto-detecting project roots, creating configuration files, and indexing source code symbols for faster retrieval.
Project Indexing Flow
Indexing is a critical step that allows the system to build a cache of symbols using Language Servers.
The flow diagram shows the sequential process of indexing a project, from resolving the root directory to populating the local LSP symbol cache.
Sources: src/serena/cli.py:640-700
Key Project Functions
find_project_root: Recursively walks up from the current working directory to find a.serena/project.ymlor a.gitdirectory._index_project: Coordinates with theLanguageServerManagerto iterate through source files and store symbol data.
Sources: src/serena/cli.py:65-103, src/serena/cli.py:674-715
Memory Management
Serena includes a robust memory system allowing agents to persist information across sessions. The memories command group provides tools for maintaining referential integrity between memory files.
| Command | Purpose |
|---|---|
list | Displays project and global memories. |
check | Validates referential integrity (stale mem: links). |
rename | Renames a memory and propagates the change to all referencing files. |
auto-prefix-references | Heuristically adds mem: prefixes to bare memory names. |
Sources: src/serena/cli.py:880-1065
Server and Dashboard Operations
The CLI provides commands to run the backend infrastructure required for agent interaction.
MCP Server Startup
The start-mcp-server command supports multiple transport protocols:
- stdio: Standard input/output (default for terminal clients).
- sse: Server-Sent Events.
- streamable-http: HTTP-based streaming.
It also manages the lifecycle of the Web Dashboard, which can be toggled via --enable-web-dashboard. The dashboard provides a visual overview of tool usage stats, logs, and project configurations.
Sources: src/serena/cli.py:215-245, README.md:120-130
Versioning and Maintenance
A specialized script, scripts/bump_version.py, is used for release management. It ensures consistency between pyproject.toml, __init__.py, and the CHANGELOG.md.
This sequence diagram depicts the automated version bumping process, including file updates and Git operations.
Sources: scripts/bump_version.py:35-85
Conclusion
The Serena CLI is a comprehensive toolset designed for both human configuration and agentic automation. By providing a structured command hierarchy for project indexing, memory management, and server operations, it ensures that the IDE-like capabilities of Serena are easily accessible and maintainable across various development environments.