{"id":26142593,"url":"https://github.com/wpdas/chain-db-cli","last_synced_at":"2026-04-20T17:05:20.188Z","repository":{"id":280956816,"uuid":"943734454","full_name":"wpdas/chain-db-cli","owner":"wpdas","description":"A command-line interface (CLI) to interact with ChainDB, a database with change history tracking.","archived":false,"fork":false,"pushed_at":"2025-03-06T07:21:54.000Z","size":1426,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-06T08:26:42.168Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wpdas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-06T07:18:39.000Z","updated_at":"2025-03-06T07:21:57.000Z","dependencies_parsed_at":"2025-03-06T08:37:21.930Z","dependency_job_id":null,"html_url":"https://github.com/wpdas/chain-db-cli","commit_stats":null,"previous_names":["wpdas/chain-db-cli"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wpdas","download_url":"https://codeload.github.com/wpdas/chain-db-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242813466,"owners_count":20189280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-11T03:57:18.877Z","updated_at":"2025-12-06T17:00:49.950Z","avatar_url":"https://github.com/wpdas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChainDB CLI\n\nA command-line interface (CLI) to interact with [ChainDB](https://github.com/wpdas/chain-db), a database with change history tracking.\n\n![ChainDB CLI Screenshot](screenshot.gif)\n\n\u003e **Note for Developers**: If you're working on the ChainDB CLI project, please check the [DEVELOPMENT.md](./DEVELOPMENT.md) file for instructions on how to set up your development environment and test the CLI locally.\n\n## Requirements\n\n- Node.js version 20.18.3 or higher\n\n## Installation\n\n### Global Installation\n\n```bash\nnpm install -g chain-db-cli\n```\n\n### Local Installation\n\n```bash\nnpm install chain-db-cli\n```\n\n## Configuration\n\nBefore using the CLI, you need to configure the ChainDB host:\n\n```bash\n# Local Chain DB (you will need to donwload and run the the chain db binary on your OS)\n# You can pick a binary here: https://github.com/wpdas/chain-db?tab=readme-ov-file#download\nchaindb config --host http://localhost:2818\n# Chain DB Test Server: (may not be always available)\nchaindb config --host https://gull-dominant-mistakenly.ngrok-free.app\n```\n\nOr without parameters to use interactive mode:\n\n```bash\nchaindb config\n```\n\n## Usage\n\n### Database Commands\n\n#### Create a database\n\n```bash\nchaindb db create --name my_database --user admin --password mypassword\n```\n\n#### Connect to a database\n\n```bash\nchaindb db connect --name my_database --user admin --password mypassword\n```\n\n#### Change database password\n\n```bash\nchaindb db change-password --name my_database --user admin --old-password oldpassword --new-password newpassword\n```\n\n### Table Commands\n\n#### List all tables\n\n```bash\nchaindb table list\n```\n\n#### Get current table data (the last record stored in the table)\n\n```bash\nchaindb table get users\n```\n\n#### Get a specific record by document ID\n\n```bash\nchaindb table get-by-id users --doc-id \"550e8400-e29b-41d4-a716-446655440000\"\n```\n\n#### Update a record by document ID\n\n```bash\nchaindb table update users --data '{\"name\": \"John\", \"age\": 30}' --doc-id \"550e8400-e29b-41d4-a716-446655440000\"\n```\n\n**Important**: When updating a record, the new data completely replaces the existing data. There is no merging of properties. If you want to preserve existing properties, you must include them in your update request.\n\nFor example, if your record has:\n\n```json\n{\n  \"name\": \"John\",\n  \"age\": 30,\n  \"city\": \"New York\",\n  \"doc_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}\n```\n\nAnd you update it with:\n\n```json\n{\n  \"age\": 31\n}\n```\n\nThe resulting record will be:\n\n```json\n{\n  \"age\": 31,\n  \"doc_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}\n```\n\nThe `name` and `city` properties are lost because the update completely replaces the data. To preserve these properties, include them in your update:\n\n```bash\nchaindb table update users --data '{\"name\": \"John\", \"age\": 31, \"city\": \"New York\"}' --doc-id \"550e8400-e29b-41d4-a716-446655440000\"\n```\n\n#### Persist new data to table\n\n```bash\nchaindb table persist users --data '{\"name\": \"John\", \"age\": 30, \"city\": \"New York\"}'\nchaindb table persist users --data '{\"name\": \"Mary\", \"age\": 25, \"city\": \"Los Angeles\"}'\n```\n\n#### Get table history\n\n```bash\nchaindb table history users --limit 10\n```\n\n#### Search records with simple criteria\n\n```bash\nchaindb table find users --criteria '{\"name\": \"John\"}' --limit 10\n```\n\n#### Search records with advanced criteria\n\n```bash\nchaindb table find-advanced users --criteria '[{\"field\": \"age\", \"operator\": \"Gt\", \"value\": 25}, {\"field\": \"name\", \"operator\": \"Contains\", \"value\": \"Jo\"}]' --limit 10\n```\n\n## Advanced Search Operators\n\n- `Eq`: Equal to (==)\n- `Ne`: Not equal to (!=)\n- `Gt`: Greater than (\u003e)\n- `Ge`: Greater than or equal to (\u003e=)\n- `Lt`: Less than (\u003c)\n- `Le`: Less than or equal to (\u003c=)\n- `Contains`: Contains (for strings and arrays)\n- `StartsWith`: Starts with (for strings)\n- `EndsWith`: Ends with (for strings)\n\n## Examples\n\n### Example 1: Create a database and add data\n\n```bash\n# Configure the host\nchaindb config --host http://localhost:2818\n\n# Create a database\nchaindb db create --name my_database --user admin --password 1234\n\n# Connect to the database\nchaindb db connect --name my_database --user admin --password 1234\n\n# List all tables in the database\nchaindb table list\n\n# Persist data to a table\nchaindb table persist users --data '{\"name\": \"John\", \"age\": 30, \"city\": \"New York\"}'\nchaindb table persist users --data '{\"name\": \"Mary\", \"age\": 25, \"city\": \"Los Angeles\"}'\n\n# Get current data (the last record stored in the table)\nchaindb table get users\n\n# Get a specific record by document ID\n# chaindb table get-by-id users --doc-id \"550e8400-e29b-41d4-a716-446655440000\"\n\n# Update a record by document ID\n# Note: This completely replaces the existing data, so include all properties you want to keep\n# First, get the record's doc_id using get or get-by-id commands\n# Then update the specific record:\n# chaindb table update users --data '{\"name\": \"John Smith\", \"age\": 31, \"city\": \"New York\"}' --doc-id \"550e8400-e29b-41d4-a716-446655440000\"\n\n# Get history\nchaindb table history users --limit 10\n```\n\n### Example 2: Advanced search\n\n```bash\n# Search for users with age greater than 25\nchaindb table find-advanced users --criteria '[{\"field\": \"age\", \"operator\": \"Gt\", \"value\": 25}]'\n\n# Search for users who live in New York and have \"Jo\" in their name\nchaindb table find-advanced users --criteria '[{\"field\": \"city\", \"operator\": \"Eq\", \"value\": \"New York\"}, {\"field\": \"name\", \"operator\": \"Contains\", \"value\": \"Jo\"}]'\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwpdas%2Fchain-db-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-cli/lists"}