> For the complete documentation index, see [llms.txt](https://databridge.gitbook.io/databridge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://databridge.gitbook.io/databridge-docs/user-guides/06_shell.md).

# Shell

This guide explains how to use the DataBridge interactive shell for quick experimentation and debugging.

## Getting Started

The DataBridge shell provides an interactive Python environment with the SDK pre-configured. To start the shell:

```bash
# Without authentication (connects to localhost:8000):
python shell.py

# With authentication (using a generated URI):
python shell.py "databridge://user:token@localhost:8000"
```

The shell will automatically:

* Connect to `http://localhost:8000` if no URI is provided
* Convert `databridge://` to `http://` for localhost URIs
* Handle authentication when a URI with credentials is provided

## Basic Usage

Once the shell starts, you'll have access to a `db` object that provides all SDK functionality:

```python
# Ingest text content
doc = db.ingest_text(
    content="Machine learning is fascinating...",
    metadata={"title": "ML Introduction"}
)
print(f"Document ID: {doc['external_id']}")

# Ingest a file
doc = db.ingest_file(
    file="research_paper.pdf",
    filename="research_paper.pdf",
    metadata={"category": "research"}
)
print(f"Document ID: {doc['external_id']}")

# Search for content
chunks = db.retrieve_chunks(
    query="What are the key findings?",
    filters={"category": "research"},
    k=4,
    min_score=0.7
)

for chunk in chunks:
    print(f"Score: {chunk['score']}")
    print(f"Content: {chunk['content']}")
    print("---")
```

## Features

The shell environment includes:

* Tab completion for methods and attributes
* Command history (use arrow keys)
* Access to all SDK functionality
* Pretty-printed results
* Built-in help system

## Getting Help

To see available methods and documentation:

```python
# List all available methods
help(db)

# Get help for a specific method
help(db.ingest_text)
help(db.retrieve_chunks)
```

## Shell Tips

1. **Command History**
   * Use up/down arrow keys to cycle through previous commands
   * Commands persist between sessions
2. **Tab Completion**
   * Press Tab to complete method names
   * Press Tab twice to see all available completions
3. **Multiline Input**
   * For long commands, you can write multiple lines
   * The shell will wait for complete Python statements
4. **Exit**
   * Use Ctrl+D or type `exit()` to exit the shell

## Common Tasks

### Document Management

```python
# List recent documents
docs = db.list_documents(limit=5)
for doc in docs:
    print(f"ID: {doc['external_id']}")
    print(f"Title: {doc['metadata'].get('title')}")
    print("---")

# Get document by ID
doc = db.get_document("doc_123")
print(f"Content Type: {doc['content_type']}")
print(f"Metadata: {doc['metadata']}")
```

### Search Operations

```python
# Basic search
results = db.retrieve_chunks("machine learning applications")

# Search with filters
results = db.retrieve_chunks(
    query="machine learning",
    filters={"category": "research", "year": 2024}
)

# Document-level search
docs = db.retrieve_docs(
    query="machine learning",
    k=4,
    min_score=0.7
)
```

### Completions

```python
# Generate completion
response = db.complete(
    prompt="Summarize the key findings",
    context_filter={"category": "research"}
)
print(f"Completion: {response['text']}")
print(f"Tokens Used: {response['usage']['total_tokens']}")
```

### Usage Analytics

```python
# Get recent usage
from datetime import datetime, timedelta

usage = db.get_recent_usage(
    since=datetime.now() - timedelta(days=7),
    operation_type="search"
)

for record in usage:
    print(f"Operation: {record['operation_type']}")
    print(f"Tokens: {record['tokens_used']}")
    print(f"Duration: {record['duration_ms']}ms")
```

## Next Steps

After getting comfortable with the shell:

1. Write scripts for automated tasks
2. Set up proper error handling
3. Implement production workflows
4. Use the SDK in your applications


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://databridge.gitbook.io/databridge-docs/user-guides/06_shell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.