Metadata-Version: 2.4
Name: wondersearch-cli
Version: 0.1.0
Summary: Command-line client for WonderSearch
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: packaging<27,>=24
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatchling<2,>=1.26; extra == 'dev'
Requires-Dist: mypy<2,>=1.15; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# WonderSearch CLI

Upload your documents and search them from the terminal.

## Install

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

From a local copy of this repository, install the CLI:

```sh
python -m pip install .
```

## Sign in

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

```sh
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:

```sh
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:

```sh
wondersearch upload ./guide.pdf --wait
```

Or upload a folder and its contents:

```sh
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:

```sh
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:

```sh
wondersearch upload resume RUN_ID --wait
```

## Search

Ask a question about the documents in your selected drive:

```sh
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:

```sh
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:

```sh
wondersearch --help
wondersearch upload --help
wondersearch search --help
```
