CLI & Lifecycle Management
Relevant source files
The following files were used as context for generating this wiki page:
CLI & Lifecycle Management encompasses the tools and processes used to install, update, maintain, and interact with the Archivum stack. This system ensures a "self-hosted" experience where users can manage their local knowledge base infrastructure with minimal overhead. The primary goal is to provide a "one-command" deployment model using Docker Compose while offering a robust Command Line Interface (CLI) for direct interaction with the wiki's core functions.
Sources: README.md:12-25, archivum-prd-v1.0.md:15-22
The lifecycle is divided into three primary phases: Deployment (installation and bootstrapping), Management (updates and maintenance), and Interaction (CLI-driven wiki operations).
Deployment and Installation
Archivum utilizes a guided installation process that configures the environment, API keys, and LLM providers. The installation can be performed via a shell bootstrap script or through a source checkout.
Installation Options
| Method | Command | Description |
|---|---|---|
| One-command Install | curl ... bootstrap.sh | bash | Downloads minimal runtime files and launches guided setup. |
| Guided Install | ./install.sh | Uses the archivum Node package to configure access and Docker. |
| Manual Install | git clone + docker compose | For developers needing fine-grained control over the build. |
Sources: README.md:27-72
Bootstrapping Flow
The bootstrap script is the entry point for new users, checking for prerequisites like Node.js and Docker before handing off control to the local CLI wizard.
The bootstrap process writes critical environment variables including ANTHROPIC_API_KEY, JWT_SECRET, and MCP_API_KEY.
Sources: README.md:29-55, README.md:139-160
CLI Interaction
The Archivum CLI (available via npx archivum wiki or within a local checkout) provides a direct bridge to the backend REST API. This allows for headless management of wiki pages, searching, and maintenance tasks.
Core CLI Commands
The CLI interacts with the backend at http://localhost:8000 using the MCP_API_KEY for authorization.
| Action | API Endpoint | Description |
|---|---|---|
ingest | POST /api/ingest | Ingests a file or URL into the wiki. |
search | GET /api/search | Performs a semantic search. |
query | POST /api/query | Asks the AI a question against the wiki. |
pages | GET /api/pages | Lists all available wiki pages. |
write | POST /api/pages | Creates or updates a page using title/content. |
lint | GET /api/lint | Checks for broken links and orphans. |
rebuild-indexes | POST /api/rebuild-indexes | Regenerates Qdrant and Kuzu indexes. |
Sources: packages/archivum-cli/src/api.js:25-46
Data Flow: CLI to Backend
The CLI serves as a wrapper for standard fetch requests, handling JSON serialization and authorization headers automatically.
Lifecycle Maintenance: Update and Uninstall
Maintaining the system involves refreshing runtime images and cleaning up resources when no longer needed.
Updates
The update.sh script refreshes runtime files, pulls the latest images from the GitHub Container Registry (ghcr.io), and restarts the stack while preserving the .env configuration and Docker volumes.
Sources: README.md:95-104
Uninstallation
The uninstaller provides granular control over what data is removed. By default, it stops containers but preserves data volumes.
--volumes: Deletes wiki data, raw uploads, SQLite, Kuzu, and Qdrant volumes.--images: Removes locally built images.--files: Deletes the local install directory.
Sources: README.md:79-93
MCP Server Lifecycle
A unique aspect of Archivum's lifecycle management is the integrated Model Context Protocol (MCP) server. This server exposes the same lifecycle and wiki management tools to external AI clients like Claude Desktop or Cursor.
Transport Modes
The MCP server supports two primary lifecycle states:
- stdio: Used for local desktop clients that launch the server as a child process.
- SSE (Server-Sent Events): Used for web-based or remote clients, running as a persistent service on port 8001.
Sources: apps/backend/archivum/mcp/server.py:276-291, archivum-prd-v1.0.md:310-318
Lifecycle Management Tools in MCP
External agents can manage the wiki lifecycle via specialized tools:
lint_wiki: Monitors health (broken links, contradictions).ingest_source: Triggers the ingestion pipeline.dispatch_command: Provides a text-based interface to run existing Archivum actions.
Sources: apps/backend/archivum/mcp/server.py:164-188, apps/backend/archivum/mcp/server.py:202-273
Summary
CLI & Lifecycle Management in Archivum provides a comprehensive toolkit for both users and AI agents to maintain the knowledge base. From the initial docker compose up to complex indexing and linting operations, the system is designed to be local-first, portable, and easily automatable through its unified CLI and MCP interfaces.
Sources: Progress.md:12-25, archivum-prd-v1.0.md:10-18