Commands Reference

This comprehensive reference covers all available commands in the OstrichDB CLI, organized by category with syntax, examples, and use cases.

Command Categories

Single-Token Commands

Commands that execute immediately without additional parameters.

Multi-Token Commands

Commands that require additional tokens (location paths, parameters) to complete the operation.

System Commands

`VERSION`

Display the current version of OstrichDB.

Syntax:

VERSION

Example:

OstrichDB> VERSION
OstrichDB CLI v2.1.0

Use Cases:

Check installed version
Verify updates
Troubleshooting compatibility

`HELP`

Display help information for commands.

Syntax:

# General help
HELP

# Specific command help
HELP <command>

Examples:

# General help
OstrichDB> HELP
Available commands:
NEW, FETCH, ERASE, RENAME, SET...

# Specific command help
OstrichDB> HELP NEW
NEW - Create new collections, clusters, records, or users
Syntax: NEW <location> [OF_TYPE <type>] [WITH <value>]

Use Cases:

Learn command syntax
Get command examples
Understand parameter options

`CLEAR`

Clear the terminal screen.

Syntax:

CLEAR

Example:

OstrichDB> CLEAR
# Terminal screen is cleared

Use Cases:

Clean up cluttered terminal
Reset visual workspace
Improve readability

`EXIT`

End the OstrichDB session and close the CLI.

Syntax:

EXIT

Example:

OstrichDB> EXIT
Goodbye!
# Returns to system terminal

Use Cases:

Normal session termination
Clean program exit
Return to system shell

`RESTART`

Restart the OstrichDB program.

Syntax:

RESTART

Example:

OstrichDB> RESTART
Restarting OstrichDB...
# Program restarts with fresh session

Use Cases:

Apply configuration changes
Clear temporary data
Recover from errors

`REBUILD`

Rebuild the DBMS and restart the program.

Syntax:

REBUILD

Example:

OstrichDB> REBUILD
Rebuilding OstrichDB...
# System rebuilds and restarts

Use Cases:

Apply system updates
Fix compilation issues
Reset system state

Data Exploration Commands

`TREE`

Display the entire data structure in a tree format.

Syntax:

TREE

Example:

OstrichDB> TREE
📁 Collections:
├── users.ostrichdb
│   ├── 📂 active
│   │   ├── 📄 john_doe: STRING: "John Doe"
│   │   └── 📄 john_email: STRING: "john@example.com"
│   └── 📂 inactive
│       └── 📄 old_user: STRING: "Former Employee"
└── products.ostrichdb
    └── 📂 electronics
        ├── 📄 laptops: INTEGER: 25
        └── 📄 phones: INTEGER: 50

Use Cases:

Visualize data structure
Understand hierarchy
Debug data organization
Overview of all data

`HISTORY`

Show the current user’s command history.

Syntax:

HISTORY

Example:

OstrichDB> HISTORY
1. NEW users.staff.alice OF_TYPE STRING WITH "Alice Johnson"
2. FETCH users.staff.alice
3. COUNT RECORDS IN users.staff
4. TREE

Use Cases:

Review recent commands
Debug query sequences
Repeat complex operations
Track user activity

`BENCHMARK`

Run performance tests on the DBMS.

Syntax:

# Basic benchmark
BENCHMARK

# Benchmark with parameters
BENCHMARK <operation> <iterations>

Examples:

# Basic system benchmark
OstrichDB> BENCHMARK
Running standard benchmark...
CREATE operations: 1000 ops/sec
FETCH operations: 2500 ops/sec
DELETE operations: 1200 ops/sec

# Specific operation benchmark
OstrichDB> BENCHMARK CREATE 1000
Testing CREATE operations (1000 iterations)...
Average: 0.8ms per operation
Total time: 800ms

Use Cases:

Performance testing
System optimization
Capacity planning
Troubleshooting slowness

Data Manipulation Commands

`NEW`

Create new collections, clusters, records, or users.

Syntax:

# Create structure only
NEW <location>

# Create record with type
NEW <location> OF_TYPE <type>

# Create record with type and value
NEW <location> OF_TYPE <type> WITH <value>

# Create user
NEW USER

Examples:

# Create collection and cluster automatically
OstrichDB> NEW inventory.electronics.laptops

# Create typed record
OstrichDB> NEW users.staff.employee_count OF_TYPE INTEGER

# Create record with value
OstrichDB> NEW products.books.title OF_TYPE STRING WITH "Database Design"

# Create array record
OstrichDB> NEW teams.engineering.members OF_TYPE []STRING WITH "Alice,Bob,Carol"

# Create user account
OstrichDB> NEW USER
Enter username: john_doe
Enter password: ********
User created successfully.

Use Cases:

Initialize data structures
Add new records
Set up databases
Create user accounts

`FETCH`

Retrieve data from collections, clusters, or records.

Syntax:

FETCH <location>

Examples:

# Fetch specific record
OstrichDB> FETCH users.staff.alice
users.staff.alice: STRING: "Alice Johnson"

# Fetch entire cluster
OstrichDB> FETCH users.staff
Cluster: users.staff
├── alice: STRING: "Alice Johnson"
├── alice_email: STRING: "alice@company.com"
└── alice_role: STRING: "Developer"

# Fetch collection overview
OstrichDB> FETCH users
Collection: users
├── Cluster: staff (3 records)
└── Cluster: contractors (1 record)

Use Cases:

View record values
Inspect cluster contents
Review collection structure
Data verification

`SET`

Assign values to records or configurations.

Syntax:

# Set record value
SET <location> TO <value>

# Set configuration
SET CONFIG <config_name> TO <value>

Examples:

# Update record value
OstrichDB> SET users.staff.alice_salary TO 80000

# Update configuration
OstrichDB> SET CONFIG AUTO_SERVE TO true

# Set complex values
OstrichDB> SET teams.engineering.tech_stack TO "React,Node.js,OstrichDB"

Use Cases:

Update existing records
Modify configurations
Change system settings
Data maintenance

`ERASE`

Delete collections, clusters, or records.

Syntax:

ERASE <location>

Examples:

# Delete specific record
OstrichDB> ERASE users.staff.old_employee

# Delete entire cluster
OstrichDB> ERASE users.inactive

# Delete collection (use with caution)
OstrichDB> ERASE old_project
Warning: This will delete the entire collection. Confirm? (y/N): y
Collection 'old_project' deleted.

Use Cases:

Remove obsolete data
Clean up test data
Delete entire structures
Data maintenance

`RENAME`

Rename existing collections, clusters, or records.

Syntax:

RENAME <old_location> TO <new_location>

Examples:

# Rename record
OstrichDB> RENAME users.staff.temp_employee TO users.staff.permanent_employee

# Rename cluster
OstrichDB> RENAME projects.temp_project TO projects.website_redesign

# Rename collection
OstrichDB> RENAME old_inventory TO current_inventory

Use Cases:

Fix naming mistakes
Reorganize data structure
Update naming conventions
Refactor data organization

`PURGE`

Remove all data from an object while maintaining the structure.

Syntax:

PURGE <location>

Examples:

# Purge cluster contents
OstrichDB> PURGE users.test_users
All records in 'users.test_users' have been removed.

# Purge collection contents
OstrichDB> PURGE temp_data
All clusters and records in 'temp_data' have been removed.

Use Cases:

Clear test data
Reset data structures
Maintain structure while removing content
Prepare for fresh data

Data Analysis Commands

`COUNT`

Count objects within a scope.

Syntax:

# Count all collections
COUNT COLLECTIONS

# Count clusters in collection
COUNT CLUSTERS [IN <collection>]

# Count records in cluster
COUNT RECORDS [IN <location>]

Examples:

# Count all collections
OstrichDB> COUNT COLLECTIONS
Total collections: 5

# Count clusters in specific collection
OstrichDB> COUNT CLUSTERS IN users
Clusters in 'users': 3

# Count records in specific cluster
OstrichDB> COUNT RECORDS IN users.staff
Records in 'users.staff': 12

# Count all records
OstrichDB> COUNT RECORDS
Total records across all collections: 247

Use Cases:

Monitor data growth
Capacity planning
Data analysis
Structure validation

`SIZE_OF`

Get the size in bytes of objects.

Syntax:

SIZE_OF <location>

Examples:

# Size of specific record
OstrichDB> SIZE_OF users.staff.alice_biography
users.staff.alice_biography: 1,247 bytes

# Size of cluster
OstrichDB> SIZE_OF users.staff
users.staff cluster: 15,432 bytes (12 records)

# Size of collection
OstrichDB> SIZE_OF users
users collection: 23,891 bytes (3 clusters, 47 records)

Use Cases:

Monitor storage usage
Identify large data objects
Optimize storage
Capacity planning

`TYPE_OF`

Get the data type of a record.

Syntax:

TYPE_OF <record_location>

Examples:

# Check record type
OstrichDB> TYPE_OF users.staff.employee_count
users.staff.employee_count: INTEGER

# Check array type
OstrichDB> TYPE_OF teams.engineering.members
teams.engineering.members: []STRING

# Check date type
OstrichDB> TYPE_OF projects.website.deadline
projects.website.deadline: DATE

Use Cases:

Verify data types
Debug type mismatches
Data validation
Schema documentation

`WHERE`

Search for records or clusters by name.

Syntax:

WHERE <search_term>

Examples:

# Find records containing "email"
OstrichDB> WHERE email
Found matches:
├── users.staff.alice_email
├── users.staff.bob_email
└── users.contractors.temp_email

# Find clusters containing "test"
OstrichDB> WHERE test
Found matches:
├── users.test_users (cluster)
└── projects.test_project (cluster)

Use Cases:

Find specific records
Locate data across collections
Search by partial names
Data discovery

Data Management Commands

`BACKUP`

Create backups of collections.

Syntax:

BACKUP <collection>

Examples:

# Backup specific collection
OstrichDB> BACKUP users
Creating backup of 'users' collection...
Backup created: users_backup_2024-01-15_10-30-00.ostrichdb

# Backup critical data
OstrichDB> BACKUP financial_records
Creating backup of 'financial_records' collection...
Backup created: financial_records_backup_2024-01-15_10-31-45.ostrichdb

Use Cases:

Data protection
Before major changes
Regular maintenance
Disaster recovery

`VALIDATE`

Check collection integrity and validate for errors.

Syntax:

VALIDATE <collection>

Examples:

# Validate collection
OstrichDB> VALIDATE users
Validating 'users' collection...
✓ File structure: OK
✓ Data integrity: OK
✓ Type consistency: OK
Collection 'users' is valid.

# Validate with issues
OstrichDB> VALIDATE corrupted_data
Validating 'corrupted_data' collection...
✗ File structure: CORRUPTED
✗ Data integrity: 3 ERRORS FOUND
Validation failed. Run repair tools or restore from backup.

Use Cases:

Check data integrity
Troubleshoot issues
Preventive maintenance
Pre-operation validation

`ISOLATE`

Quarantine a collection to prevent changes.

Syntax:

ISOLATE <collection>

Examples:

# Isolate collection
OstrichDB> ISOLATE sensitive_data
Collection 'sensitive_data' has been isolated.
No further modifications allowed.

# Attempt to modify isolated collection
OstrichDB> NEW sensitive_data.cluster.record OF_TYPE STRING WITH "test"
Error: Collection 'sensitive_data' is isolated and cannot be modified.

Use Cases:

Protect critical data
Prevent accidental changes
Compliance requirements
Data preservation

`CHANGE_TYPE`

Change the data type of an existing record.

Syntax:

CHANGE_TYPE <record_location> TO <new_type>

Examples:

# Change string to integer
OstrichDB> CHANGE_TYPE products.electronics.laptop_count TO INTEGER
Warning: Current value "25" will be converted to INTEGER.
Proceed? (y/N): y
Type changed: products.electronics.laptop_count is now INTEGER: 25

# Change to array type
OstrichDB> CHANGE_TYPE users.staff.skills TO []STRING
Warning: Current value will be converted to array format.
Current: "Programming"
New: ["Programming"]
Proceed? (y/N): y

Use Cases:

Fix type mistakes
Schema evolution
Data migration
Type optimization

Security Commands

`LOCK`

Change collection access modes.

Syntax:

# Set to read-only
LOCK <collection> -r

# Set to inaccessible
LOCK <collection>

Examples:

# Lock collection as read-only
OstrichDB> LOCK financial_data -r
Collection 'financial_data' locked in read-only mode.

# Lock collection completely
OstrichDB> LOCK archived_data
Collection 'archived_data' locked. No access allowed.

# Attempt to modify locked collection
OstrichDB> NEW financial_data.new_cluster.record OF_TYPE STRING WITH "test"
Error: Collection 'financial_data' is locked in read-only mode.

Use Cases:

Protect important data
Prevent accidental modifications
Enforce read-only access
Data security

`UNLOCK`

Remove collection access restrictions.

Syntax:

UNLOCK <collection>

Examples:

# Unlock collection
OstrichDB> UNLOCK financial_data
Collection 'financial_data' unlocked. Full access restored.

# Verify unlock
OstrichDB> NEW financial_data.test.record OF_TYPE STRING WITH "accessible"
Record created successfully.

Use Cases:

Restore full access
Enable modifications
Remove restrictions
Maintenance operations

`ENC`

Encrypt a collection.

Syntax:

ENC <collection>

Examples:

# Encrypt collection
OstrichDB> ENC sensitive_data
Enter encryption password: ********
Confirm password: ********
Encrypting collection 'sensitive_data'...
Collection encrypted successfully.

# Encrypted collection access
OstrichDB> FETCH sensitive_data.cluster.record
Enter decryption password: ********
sensitive_data.cluster.record: STRING: "confidential information"

Use Cases:

Protect sensitive data
Compliance requirements
Data security
Confidential information

`DEC`

Decrypt an encrypted collection.

Syntax:

DEC <collection>

Examples:

# Decrypt collection
OstrichDB> DEC sensitive_data
Enter decryption password: ********
Warning: This will permanently decrypt the collection.
Proceed? (y/N): y
Decrypting collection 'sensitive_data'...
Collection decrypted successfully.

Use Cases:

Remove encryption
Permanent decryption
Data migration
Access simplification

Server Commands

`SERVE` / `SERVER`

Start the built-in HTTP server.

Syntax:

SERVE
# or
SERVER

Examples:

# Start server
OstrichDB> SERVE
Starting OstrichDB HTTP Server...
Server running on http://localhost:8080
Press Ctrl+C to stop server.

# Server with custom port (if configured)
OstrichDB> SERVE
Server running on http://localhost:8089
Ready to accept HTTP requests.

Use Cases:

Enable HTTP API access
Web application integration
Remote database access
Client application connectivity

`AGENT`

Start the natural language processor (experimental).

Syntax:

AGENT

Examples:

# Start NLP agent (requires server running)
OstrichDB> AGENT
Starting Natural Language Agent...
Agent ready. Type natural language queries.

Agent> Create a new user record for Alice with email alice@company.com
Processing: Creating user record...
NEW users.staff.alice OF_TYPE STRING WITH "Alice"
NEW users.staff.alice_email OF_TYPE STRING WITH "alice@company.com"
Operations completed successfully.

Agent> exit
Returning to standard CLI mode.

Use Cases:

Natural language queries
Simplified database interaction
User-friendly interface
Experimental features

User Management Commands

`NEW USER`

Create a new user account.

Syntax:

NEW USER

Example:

OstrichDB> NEW USER
Creating new user account...
Enter username: john_doe
Enter password: ********
Confirm password: ********
Enter email (optional): john@company.com
User 'john_doe' created successfully.

Use Cases:

Multi-user setups
Access control
User management
Authentication setup

`LOGOUT`

Log out the current user.

Syntax:

LOGOUT

Example:

OstrichDB> LOGOUT
Logging out user 'john_doe'...
User logged out successfully.
Please log in to continue.

Login:

Use Cases:

Switch users
Security practices
Session management
Multi-user environments

Import/Export Commands

`IMPORT`

Import data from CSV or JSON files.

Syntax:

IMPORT <file_path> TO <collection.cluster>

Examples:

# Import CSV file
OstrichDB> IMPORT /path/to/users.csv TO users.imported
Importing CSV file...
✓ Processed 250 records
✓ Created users.imported cluster
Import completed successfully.

# Import JSON file
OstrichDB> IMPORT /path/to/products.json TO inventory.products
Importing JSON file...
✓ Processed 150 records
✓ Created inventory.products cluster
Import completed successfully.

Use Cases:

Data migration
Bulk data loading
External data integration
System initialization

Maintenance Commands

`DESTROY`

Completely destroy the entire DBMS (use with extreme caution).

Syntax:

DESTROY

Example:

OstrichDB> DESTROY
⚠️  WARNING: This will permanently delete ALL data, users, configs, and logs.
Type 'DESTROY EVERYTHING' to confirm: DESTROY EVERYTHING
Destroying all OstrichDB data...
✓ All collections deleted
✓ User accounts deleted
✓ Configuration files deleted
✓ Logs cleared
✓ System reset complete
OstrichDB has been completely reset.

Use Cases:

Complete system reset
Start fresh installation
Remove all traces
Nuclear option

Query Chaining

Chain Operator (`&&`)

Execute multiple commands in sequence.

Syntax:

<command1> && <command2> && <command3>

Examples:

# Create and verify
OstrichDB> NEW users.staff.alice OF_TYPE STRING WITH "Alice Johnson" && FETCH users.staff.alice
Creating record...
users.staff.alice: STRING: "Alice Johnson"

# Complex operations
OstrichDB> NEW project.webapp.name OF_TYPE STRING WITH "Company Website" && NEW project.webapp.status OF_TYPE STRING WITH "Active" && COUNT RECORDS IN project.webapp && TREE

# Error handling
OstrichDB> NEW invalid.type OF_TYPE INVALID_TYPE WITH value && FETCH valid.record
Error in first command: Invalid type 'INVALID_TYPE'
Remaining commands skipped.

Use Cases:

Batch operations
Related tasks
Efficient workflows
Atomic operations

Best Practices

Command Usage Tips

Use HELP: Always check command syntax with HELP <command>
Validate First: Use VALIDATE before major operations
Backup Before Changes: Use BACKUP before destructive operations
Check Types: Use TYPE_OF to verify data types
Monitor Size: Use SIZE_OF to track data growth

Error Prevention

Test Queries: Try operations on test data first
Use TREE: Visualize structure before complex operations
Chain Carefully: Understand that errors stop chain execution
Validate Paths: Ensure location paths are correct
Check Permissions: Verify access before operations

Performance Tips

Use Specific Paths: Avoid broad FETCH operations
Regular Cleanup: Use ERASE to remove unused data
Monitor Performance: Use BENCHMARK regularly
Validate Regularly: Use VALIDATE to catch issues early
Optimize Queries: Chain related operations together

Next Steps

Master these commands by:

Understanding Data Types - Learn the type system
Configuring OstrichDB - Customize your setup
Practice: Use these commands with real data
Experiment: Try different combinations and patterns

This command reference provides the foundation for all OstrichDB CLI operations. Bookmark this page and refer to it as you build your database management workflows.

Commands Reference

Commands Reference

Command Categories

Single-Token Commands

Multi-Token Commands

System Commands

VERSION

HELP

CLEAR

EXIT

RESTART

REBUILD

Data Exploration Commands

TREE

HISTORY

BENCHMARK

Data Manipulation Commands

NEW

FETCH

SET

ERASE

RENAME

PURGE

Data Analysis Commands

COUNT

SIZE_OF

TYPE_OF

WHERE

Data Management Commands

BACKUP

VALIDATE

ISOLATE

CHANGE_TYPE

Security Commands

LOCK

UNLOCK

ENC

DEC

Server Commands

SERVE / SERVER

AGENT

User Management Commands

NEW USER

LOGOUT

Import/Export Commands

IMPORT

Maintenance Commands

DESTROY

Query Chaining

Chain Operator (&&)

Best Practices

Command Usage Tips

Error Prevention

Performance Tips

Next Steps

`VERSION`

`HELP`

`CLEAR`

`EXIT`

`RESTART`

`REBUILD`

`TREE`

`HISTORY`

`BENCHMARK`

`NEW`

`FETCH`

`SET`

`ERASE`

`RENAME`

`PURGE`

`COUNT`

`SIZE_OF`

`TYPE_OF`

`WHERE`

`BACKUP`

`VALIDATE`

`ISOLATE`

`CHANGE_TYPE`

`LOCK`

`UNLOCK`

`ENC`

`DEC`

`SERVE` / `SERVER`

`AGENT`

`NEW USER`

`LOGOUT`

`IMPORT`

`DESTROY`

Chain Operator (`&&`)