WonderSearch CLI

Upload your documents and search them from the terminal.

Install

Requires Python 3.10–3.14 on macOS, Windows, or Linux.

pip install wondersearch-cli

Sign in

Set up your WonderSearch account in the Console, then run:

wondersearch login

Your browser will open. Check that the verification code matches the one in your terminal, then sign in and choose Connect CLI. If you are already signed in, you can connect that account directly.

If the browser does not open, run wondersearch login --no-browser and open the printed link on the same computer.

Choose where to work

List your workspaces and drives, then select the ones you want to use:

wondersearch workspace list
wondersearch workspace use WORKSPACE_ID
wondersearch drive list
wondersearch drive use DRIVE_ID

Replace WORKSPACE_ID and DRIVE_ID with IDs from the lists. The CLI remembers your selections for later commands.

Upload documents

Upload a file:

wondersearch upload ./guide.pdf --wait

Or upload a folder and its contents:

wondersearch upload ./docs --recursive --wait

Supported formats are PDF, Word (.docx), plain text, and Markdown. --wait keeps the command running until your documents are ready to search.

To preview a folder upload without sending files:

wondersearch upload ./docs --recursive --dry-run

The service operator selects the search model; there is no CLI model-selection option. The response's model field identifies the model actually used. The server enforces the active model's token limit and the 16,384 UTF-8 byte limit. Search returns at most 10 results; search --limit is not supported. Use --no-group-by-document to allow multiple passages per document, or --group-by-document to group them. --timeout-ms sets a server deadline from 1 to 20,000 milliseconds; omission uses the effort default configured by the server. This deadline is distinct from upload and processing timeouts.

Uploading the same file again creates another document. To update an existing document, use wondersearch upload ./guide.pdf --replace DOCUMENT_ID --wait.

If an upload is interrupted, use the run ID printed in the terminal to resume it:

wondersearch upload resume RUN_ID --wait

Search

Ask a question about the documents in your selected drive:

wondersearch search "How do I reset my password?"

To search a specific folder, add --folder FOLDER_ID.

Other useful commands

Task	Command
Check which account is signed in	wondersearch whoami
List documents	wondersearch document list
List folders	wondersearch folder list
Create a folder	wondersearch folder create "Research"
Check account usage	wondersearch usage
Check storage	wondersearch storage
Sign out of the CLI	wondersearch logout

Signing out of the CLI leaves you signed in to the Console.

Use in scripts

Add --json to a command for output your script can read:

wondersearch search "What is our refund policy?" --json

For automation, sign in with an API key using wondersearch login --api-key. Paste the key at the hidden prompt. API keys can only access the workspace and actions they have permission to use.

Get help

Use --help to see the available commands and options:

wondersearch --help
wondersearch upload --help
wondersearch search --help

Contributing

To install from source, run this command from the repository root in an active Python virtual environment:

python -m pip install .