Install the bds command

  1. Install BigdataSight 1.2 in Applications and open it.
  2. Choose Command Line → Set Up bds… and select your shell.
  3. Click Copy Install Command, review it, and run it in Terminal.
  4. Run the checks below. If the command is not found, open a new terminal.
bds --version
bds --help

The installer creates ~/.local/bin/bdsand adds it to your shell's PATH. Use Command Line → Quick Start… for examples and Command Reference… for help.

Choose data access

Open Settings → External Access → Data access, choose an access level, and add the local files or folders you want to use.

  • No access: sources are unavailable to commands and AI clients.
  • Structure only: inspect schemas, compare structure, and request schema-only query plans.
  • Structure and data: also query rows, calculate statistics, compare data, and export results.

Viewer supports local Parquet and CSV. Pro adds the other supported local formats, local Delta and Iceberg table directories, and remote operations. For SQLite or Excel, choose the table, view, or worksheet to use.

For remote data, open Manage Connections → External Access and choose the access level and permitted buckets or paths. Add output folders separately in Settings → External Access → Export locations before exporting.

Removing a file or folder, or changing its access level, affects subsequent operations and result retrieval. Information already returned to a client cannot be recalled. Your AI provider's settings determine how it handles that information.

Copy a query from the app

  1. Open a supported source, allow it in External Access, and write or select one SELECT statement in the SQL console.
  2. Open the menu beside Run and choose Copy as Command….
  3. Choose your shell, row limit, and timeout. Review and copy the generated command.
  4. Run it in Terminal. Use the command reference for comparison, export, and task operations.
bds files list --format json
bds query --help
bds diff data --help
bds export --help
bds jobs --help

Queries return at most 1,000 result rows. Full query exports have their own scope and format limits. Copy as Command currently generates SQL commands; comparison and export commands are documented in the reference.

Connect an AI client

Your client must support starting a local Model Context Protocol (MCP) command on this Mac. Use your own AI client and any account or plan its provider requires.

  1. Choose Agent → Connect AI Client….
  2. Select Codex, Claude Code, OpenCode, or Other JSON client.
  3. In Quick setup, preview the instructions and click Copy Setup Prompt.
  4. Paste the prompt into your client, review its proposed changes, and reload the client after setup.

For manual configuration, select Manual setup and use Copy Manual Configuration. Preserve your client's other settings.

Check the first connection

Under Try a prompt, click Copy Check Prompt and send it to your client. The same prompt is below. Empty inventories are a valid connection result.

Use BigdataSight's MCP tools to check the first connection:
1. Call `bigdatasight_sources_list` once with no arguments.
2. Call `bigdatasight_recipes_list` once with no arguments.
3. Call `bigdatasight_local_files_list` once with no arguments.
4. Report whether the calls completed and give the number of approved sources, saved Recipes and allowed local files.
5. If a call failed, report the connection status and the next setup step.

Stop after reporting the result.

Next, use Copy Local File Prompt to inspect a selected source. With data access, ask for a query or comparison. With Pro, longer supported operations can run as independent tasks; reconnect later to check progress or retrieve results.

Ask your first data question

Choose a local Parquet or CSV file, add it in External Access, and enable Structure and data. Send the prompt below to your connected AI client, replacing the file description with your own.

Use BigdataSight to inspect the local sales file I added.
Show the schema and a short preview, then explain what one row appears to represent.
Ask me which measure and date range I want to analyze.
Show the proposed SQL, run the agreed calculation, and report the result with the row count and any result limits.

Review the grouping, filters, and meaning of the returned result. A preview helps form a question; it does not establish a conclusion about every row. See the worked AI and SQL example for a calculation where the row meaning changes the answer.

Keep longer operations running

With Pro, start a supported query, comparison, export, or verification as an independent task. Keep its task ID to check progress, cancel work, or retrieve the result from a later command or AI client session.

Start with bds jobs --help or ask your client to use an independent task for the operation. Keep your Mac awake while work runs. A client disconnect does not by itself cancel an independent task. After restarting the Mac, check the task status before submitting the operation again.

Verification with Pro

Open Agent → Verification Recipes to review or add a Recipe. Select an approved saved source and the intended table versions, then use Copy Dry Run Promptin the client connection window before requesting a verification run.

Pass, Warn, Fail, and Inconclusive retain their meaning in the app and client. Inconclusive means the available evidence did not establish the rule.

If setup or an operation fails

  • Move the app to Applications before copying installation or client setup instructions.
  • After moving or replacing the app, copy its setup instructions again and reload the client.
  • If a source is missing or denied, check its access level and file/folder or connection selection in External Access.
  • If an export is denied, check its output folder in Export locations and the required Pro feature.
  • Use Copy App Diagnostics at the bottom of the connection window when contacting support.

Updating from 1.1

Update the Mac App Store edition through Apple, or download the latest Direct edition from the download page. After updating, check your source selections in Settings → External Access and copy fresh client setup instructions from Agent → Connect AI Client…. Use the steps above to set up the command line and reconnect your client.

Purchases and updates remain with their original channel. See known limitationsor contact support for a workflow not covered here.