Skip to main content

Database Commands

The db command group manages isolated databases. Each database is a self-contained workspace with its own sources, knowledge graph, chat history, workflows, triggers, and search indexes.

chaoscypher db --help

List Databases​

Show all databases with name, size, last modified date, and status:

chaoscypher db list

Sample Output (Table)​

                  Databases
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name           ┃    Size ┃ Modified            ┃ Status  ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ default        │ 2.3 MB  │ 2026-03-09 14:22:01 │ current │
│ research-2026  │ 8.7 MB  │ 2026-03-08 10:15:43 │         │
│ medical_notes  │ 1.1 MB  │ 2026-02-28 09:04:17 │         │
└────────────────┴─────────┴─────────────────────┴─────────┘

Sample Output (JSON)​

chaoscypher db list --json
[
  {
    "name": "default",
    "path": "/home/user/.local/share/chaoscypher/databases/default",
    "size": 2411724,
    "last_modified": "2026-03-09T14:22:01+00:00",
    "is_current": true
  },
  {
    "name": "research-2026",
    "path": "/home/user/.local/share/chaoscypher/databases/research-2026",
    "size": 9122816,
    "last_modified": "2026-03-08T10:15:43+00:00",
    "is_current": false
  }
]

Sample Output (Quiet)​

chaoscypher db list --quiet
default
research-2026
medical_notes

Options​

OptionDescription
--jsonOutput as JSON
--quiet, -qOnly show database names

Current Database​

Show which database is currently active:

chaoscypher db current

Sample Output​

default

Sample Output (Verbose)​

chaoscypher db current -v
Current database: default
  Location: /home/user/.local/share/chaoscypher/databases/default
  Size: 2.3 MB
  Last modified: 2026-03-09 14:22:01

If the database directory exists but has not been initialized:

Current database: my-project
  Location: /home/user/.local/share/chaoscypher/databases/my-project
  Database not initialized

Options​

OptionDescription
--verbose, -vShow detailed information (location, size, last modified)

Create a Database​

chaoscypher db create <name>

Creates a new database with the required directory structure, including app.db (SQLite) and search/ (search indexes). The database is not automatically switched to after creation.

Database names must be alphanumeric (hyphens and underscores allowed). The pattern is [a-zA-Z0-9_-]+.

Sample Output​

chaoscypher db create research-2026
Creating database 'research-2026'...

Created database 'research-2026'
  Location: /home/user/.local/share/chaoscypher/databases/research-2026

Switch to it with: chaoscypher db switch research-2026

Error: Invalid Name​

chaoscypher db create "my project!"
Invalid database name.
Names must be alphanumeric (hyphens and underscores allowed).

Error: Already Exists​

chaoscypher db create default
Database already exists: default

Switch Database​

Set the default database for all subsequent CLI commands:

chaoscypher db switch <name>

The database must already exist (have an initialized app.db).

Sample Output​

chaoscypher db switch research-2026
Switched to database 'research-2026'

Error: Not Found​

chaoscypher db switch nonexistent
Database not found: nonexistent

Create it with: chaoscypher db create nonexistent

Database Info​

Show detailed information about a specific database, including filesystem metadata and content counts (nodes, edges, templates):

chaoscypher db info <name>

Sample Output (Table)​

chaoscypher db info default
╭──────────── Database ────────────╮
│ default (current)                │
╰──────────────────────────────────╯
  Location: /home/user/.local/share/chaoscypher/databases/default
  Size: 2.3 MB
  Modified: 2026-03-09 14:22:01

  Contents:
    Nodes: 1,247
    Edges: 3,891
    Templates: 12

Sample Output (JSON)​

chaoscypher db info default --json
{
  "name": "default",
  "path": "/home/user/.local/share/chaoscypher/databases/default",
  "size": 2411724,
  "last_modified": "2026-03-09T14:22:01+00:00",
  "is_current": true,
  "contents": {
    "nodes": 1247,
    "edges": 3891,
    "templates": 12
  }
}

Error: Not Found​

chaoscypher db info nonexistent
Database not found: nonexistent

Expected location: /home/user/.local/share/chaoscypher/databases/nonexistent

Options​

OptionDescription
--jsonOutput as JSON

Delete a Database​

Permanently remove a database and all its data:

chaoscypher db delete <name>

Sample Output (With Confirmation)​

chaoscypher db delete old-project
WARNING: This will permanently delete:
  - All knowledge graph data
  - All sources and extractions
  - All workflows and triggers
  - Search indexes

  Location: /home/user/.local/share/chaoscypher/databases/old-project

Are you sure you want to delete 'old-project'? [y/N]: y
Deleted database 'old-project'

Skip Confirmation​

chaoscypher db delete old-project --yes
Deleted database 'old-project'

Options​

OptionDescription
--yes, -ySkip confirmation prompt
Safety checks
  • Cannot delete the default database
  • Cannot delete the currently active database (switch to another database first)

Error: Cannot Delete Default​

chaoscypher db delete default
Cannot delete the 'default' database.

Error: Cannot Delete Current​

chaoscypher db delete research-2026
Cannot delete the current database.

Switch to another database first:
  chaoscypher db switch default

Storage Location​

Databases are stored under the platform-specific data directory:

PlatformPath
Linux~/.local/share/chaoscypher/databases/{db_name}/
macOS~/Library/Application Support/chaoscypher/databases/{db_name}/
Windows%LOCALAPPDATA%\chaoscypher\databases\{db_name}\

Each database directory contains:

{db_name}/
└── app.db       # All data: sources, graph, chat, workflows, search indexes (FTS5 + sqlite-vec)

You can override the data directory with the CHAOSCYPHER_DATA_DIR environment variable:

export CHAOSCYPHER_DATA_DIR=/custom/path
# Databases will be stored at /custom/path/databases/{db_name}/