CLI Connector

The Smart Search SDK provides CLI commands to interact with third-party connectors such as GitHub, Google Drive, Google Calendar, Google Mail, and Chief Retrieval.

Overview

Connector commands allow you to:

• Connect to third-party services

• Disconnect from third-party services

• Search within connected services using natural language queries

Prerequisites

Before using connector commands, ensure you have:

• Smart Search SDK installed

• SMARTSEARCH_BASE_URL environment variable set

• Valid authentication credentials

Available Commands

Connector - Connect

Initiate integration with a third-party connector.

Usage

smart-search connector connect --app-name <APP_NAME> [OPTIONS]

Parameters

Parameter	Required	Type	Description
--app-name	Yes	String	App name to connect to. Options: github, google_mail, google_calendar, google_drive, chief_retrieval
--bosa-token	No	String	BOSA token for authentication (optional)
--callback-url	No	String	OAuth callback URL (defaults to Smart Search's URL)
--view	No	String	Output format: pretty or json (default: pretty)

Examples

Interactive mode:

smart-search connector connect

Connect to GitHub:

smart-search connector connect --app-name github --bosa-token "your-token"

Connect to Google Drive with custom callback:

smart-search connector connect \
  --app-name google_drive \
  --callback-url "https://your-app.com/callback"

Response

When OAuth setup is required:

{
  "status": "setup_required",
  "message": "Please authenticate with the service",
  "setup_url": "https://oauth.provider.com/authorize?..."
}

When already connected:

{
  "status": "connected",
  "message": "Successfully connected to GitHub"
}

---

Connector - Disconnect

Remove integration with a third-party connector.

Usage

smart-search connector disconnect --app-name <APP_NAME> [OPTIONS]

Parameters

Parameter	Required	Type	Description
--app-name	Yes	String	App name to disconnect from. Options: github, google_mail, google_calendar, google_drive, chief_retrieval
--bosa-token	No	String	BOSA token for authentication (optional)
--view	No	String	Output format: pretty or json (default: pretty)

Examples

Disconnect from GitHub:

smart-search connector disconnect --app-name github

Disconnect with BOSA token:

smart-search connector disconnect \
  --app-name google_calendar \
  --bosa-token "your-token"

Response

{
  "status": "disconnected",
  "message": "Successfully disconnected from GitHub"
}

---

Connector - Search

Search a connected third-party service using natural language queries.

Usage

smart-search connector search --query "<QUERY>" --app-name <APP_NAME> [OPTIONS]

Parameters

Parameter	Required	Type	Description
--query	Yes	String	Natural language search query
--app-name	Yes	String	App name to search. Options: github, google_mail, google_calendar, google_drive, chief_retrieval
--bosa-token	No	String	BOSA token for authentication (optional)
--view	No	String	Output format: table or json (default: table)
--stream	No	Boolean	Enable streaming response (default: false)

Examples

Search GitHub issues:

smart-search connector search \
  --query "open issues about authentication" \
  --app-name github

Search Google Calendar:

smart-search connector search \
  --query "meetings with Alice next week" \
  --app-name google_calendar \
  --view json

Search Google Drive with streaming:

smart-search connector search \
  --query "Q2 financial reports" \
  --app-name google_drive \
  --stream true

Response (Table View)

┏━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ No ┃ Title       ┃ Content Preview ┃ Source        ┃ Score  ┃
┡━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 1  │ Issue #123  │ Authentication… │ github.com/…  │ 0.95   │
│ 2  │ PR #456     │ Fix auth flow…  │ github.com/…  │ 0.87   │
└────┴─────────────┴─────────────────┴───────────────┴────────┘
✓ Found 2 results.

Response (JSON View)

{
  "data": [
    {
      "content": "Authentication issue in OAuth flow...",
      "metadata": {
        "title": "Issue #123: Fix OAuth authentication",
        "source": "https://github.com/user/repo/issues/123"
      },
      "confidence_score": 0.95
    }
  ]
}

Authentication

The connector commands support two authentication modes:

1. Default Mode: Uses Smart Search's internal BOSA credentials

   smart-search connector connect --app-name github

2. BOSA Token Mode: Uses provided BOSA token

   smart-search connector connect \
     --app-name github \
     --bosa-token "your-token"

Error Handling

All commands provide clear error messages:

❌ Error occurred during connector connection
Details: Connection timeout - please check your network

Best Practices

1. Use appropriate app names: Ensure the app name matches exactly (case-sensitive)

2. Handle setup URLs: For OAuth connectors, visit the setup URL to complete authentication

3. Stream large results: Use --stream true for better performance with large result sets

4. JSON for automation: Use --view json when integrating with scripts or CI/CD pipelines

5. Secure tokens: Never hardcode BOSA tokens in scripts; use environment variables

Common Use Cases

Searching GitHub Issues

smart-search connector search \
  --query "bugs related to payment processing" \
  --app-name github \
  --view table

Finding Email Threads

smart-search connector search \
  --query "emails from john about project alpha" \
  --app-name google_mail

Locating Calendar Events

smart-search connector search \
  --query "meetings scheduled for tomorrow" \
  --app-name google_calendar

Searching Documents

smart-search connector search \
  --query "design documents from last quarter" \
  --app-name google_drive