> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jjhub.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Find repositories, issues, code, and users across JJHub

# Search

JJHub provides full-text search across the platform. You can search for repositories, issues, code, and users from the CLI or via the API. Search results are paginated and can be filtered, sorted, and output as JSON for programmatic use.

## What You Can Search

| Resource         | CLI Command           | API Endpoint                   | What's Indexed                               |
| ---------------- | --------------------- | ------------------------------ | -------------------------------------------- |
| **Repositories** | `jjhub search repos`  | `GET /api/search/repositories` | Name, description, topics                    |
| **Issues**       | `jjhub search issues` | `GET /api/search/issues`       | Title, body, comments                        |
| **Code**         | `jjhub search code`   | `GET /api/search/code`         | File contents across all public repositories |
| **Users**        | *(API only)*          | `GET /api/search/users`        | Username, display name, email                |

***

## CLI Search Commands

### Search Repositories

Find repositories by name, description, or topic.

```bash theme={null}
# Basic search
jjhub search repos "jj native"

# Limit results
jjhub search repos "workflow engine" -L 10

# JSON output for scripting
jjhub search repos "jj native" --json
```

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `-L, --limit <n>` | Maximum number of results to return (default: 30) |

Example output:

```
NAME                    DESCRIPTION                          STARS  UPDATED
alice/jj-tools          CLI utilities for jj workflows       42     2026-03-01
bob/jj-hooks            Git hooks compatible with jj         18     2026-02-28
acme/jj-migration       Migrate from git to jj               7     2026-02-15
```

### Search Issues

Search across issue titles and bodies.

```bash theme={null}
# Search for issues mentioning authentication
jjhub search issues "authentication"

# Filter by state
jjhub search issues "landing request" -s open

# Only closed issues
jjhub search issues "fix crash" -s closed

# Limit results
jjhub search issues "bookmark" -L 5
```

| Flag                  | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `-s, --state <state>` | Filter by state: `open`, `closed`, `all` (default: all) |
| `-L, --limit <n>`     | Maximum number of results to return (default: 30)       |

Example output:

```
REPO              NUMBER  TITLE                          STATE   UPDATED
alice/my-project  42      Auth fails on Sign in with Key open    2026-03-01
bob/api-server    17      Token refresh broken           closed  2026-02-20
```

### Search Code

Search file contents across repositories.

```bash theme={null}
# Search for a function name
jjhub search code "import_refs"

# Search for a specific pattern
jjhub search code "fn handle_landing_request"

# Limit results
jjhub search code "BookmarkResolver" -L 10
```

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `-L, --limit <n>` | Maximum number of results to return (default: 30) |

Example output:

```
REPO              FILE                         MATCH
alice/jj-tools    src/import.rs:42             pub fn import_refs(repo: &Repository) {
bob/jj-hooks      lib/reconcile.rs:18          use jj_lib::import_refs;
acme/jj-server    internal/vcs/import.go:55    // import_refs synchronizes git refs
```

***

## API Search Endpoints

All search endpoints are under `/api/search/` and accept a `q` query parameter. Results are paginated using standard JJHub pagination (see [Pagination](/api-reference/pagination)).

<Note>
  Search endpoints have a stricter rate limit of **30 requests per minute**, separate from the general API rate limit of 5,000 requests per hour.
</Note>

### Search Repositories

```bash theme={null}
curl "https://api.jjhub.tech/api/search/repositories?q=jj+native" \
  -H "Authorization: token jjhub_your_token"
```

**Query parameters:**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `q`       | string  | Search query (required)                  |
| `cursor`  | string  | Opaque cursor for the next page          |
| `limit`   | integer | Results per page (default: 30, max: 100) |

**Response (200 OK):**

```json theme={null}
[
  {
    "id": 1,
    "owner": {
      "login": "alice",
      "id": 1
    },
    "name": "jj-tools",
    "full_name": "alice/jj-tools",
    "description": "CLI utilities for jj workflows",
    "private": false,
    "stars_count": 42,
    "topics": ["jj", "cli", "workflow"],
    "updated_at": "2026-03-01T12:00:00Z"
  }
]
```

### Search Issues

```bash theme={null}
curl "https://api.jjhub.tech/api/search/issues?q=authentication&state=open" \
  -H "Authorization: token jjhub_your_token"
```

**Query parameters:**

| Parameter | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `q`       | string  | Search query (required)                        |
| `state`   | string  | Filter: `open`, `closed`, `all` (default: all) |
| `cursor`  | string  | Opaque cursor for the next page                |
| `limit`   | integer | Results per page (default: 30, max: 100)       |

**Response (200 OK):**

```json theme={null}
[
  {
    "id": 1,
    "number": 42,
    "title": "Auth fails on Sign in with Key",
    "state": "open",
    "body": "When attempting to authenticate via Sign in with Key...",
    "user": {
      "login": "alice",
      "id": 1
    },
    "repository": {
      "full_name": "alice/my-project"
    },
    "created_at": "2026-02-28T10:00:00Z",
    "updated_at": "2026-03-01T15:30:00Z"
  }
]
```

### Search Code

```bash theme={null}
curl "https://api.jjhub.tech/api/search/code?q=import_refs" \
  -H "Authorization: token jjhub_your_token"
```

**Query parameters:**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `q`       | string  | Search query (required)                  |
| `cursor`  | string  | Opaque cursor for the next page          |
| `limit`   | integer | Results per page (default: 30, max: 100) |

**Response (200 OK):**

```json theme={null}
[
  {
    "name": "import.rs",
    "path": "src/import.rs",
    "repository": {
      "full_name": "alice/jj-tools"
    },
    "content": "pub fn import_refs(repo: &Repository) {",
    "line_number": 42
  }
]
```

### Search Users

User search is available via the API only (no CLI command).

```bash theme={null}
curl "https://api.jjhub.tech/api/search/users?q=alice" \
  -H "Authorization: token jjhub_your_token"
```

**Query parameters:**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `q`       | string  | Search query (required)                  |
| `cursor`  | string  | Opaque cursor for the next page          |
| `limit`   | integer | Results per page (default: 30, max: 100) |

**Response (200 OK):**

```json theme={null}
[
  {
    "id": 1,
    "login": "alice",
    "full_name": "Alice Smith",
    "avatar_url": "https://api.jjhub.tech/avatars/alice",
    "created_at": "2026-01-15T10:00:00Z"
  }
]
```

***

## Pagination

Search results follow JJHub's standard cursor-based pagination model. Use the `cursor` and `limit` query parameters to navigate through results. The response includes:

* **`next_cursor`** field in the response body for fetching the next page
* **`Link` header** with `rel="next"` URL for navigating pages
* **`X-Total-Count` header** with the total number of matching results

```bash theme={null}
# Fetch results with a custom limit
curl "https://api.jjhub.tech/api/search/repositories?q=jj&limit=10" \
  -H "Authorization: token jjhub_your_token"
```

In the CLI, use `--limit` to control the number of results returned in a single request:

```bash theme={null}
jjhub search repos "jj" -L 50
```

See the [Pagination guide](/api-reference/pagination) for full details on how pagination works across the API.

***

## JSON Output for Programmatic Use

All CLI search commands support `--json` output for scripting and automation:

```bash theme={null}
# Get JSON output
jjhub search repos "workflow" --json

# Pipe to jq for filtering
jjhub search repos "workflow" --json | jq '.[].full_name'

# Use in shell scripts
for repo in $(jjhub search repos "jj" --json | jq -r '.[].full_name'); do
  echo "Found: $repo"
done
```

For AI and LLM pipelines, use `--toon` output (Token-Oriented Object Notation) which produces the same data in a format optimized for token efficiency:

```bash theme={null}
jjhub search repos "workflow" --toon
```

***

## Search Tips

### Exact Phrases

Wrap your query in double quotes to search for an exact phrase:

```bash theme={null}
jjhub search repos '"landing request"'
jjhub search code '"fn resolve_conflicts"'
```

### Combining Terms

Multiple words are matched as an AND query by default -- all terms must be present:

```bash theme={null}
# Finds repos with both "jj" and "workflow" in their name/description
jjhub search repos "jj workflow"
```

### Common Patterns

**Find all repositories by a user:**

```bash theme={null}
jjhub search repos "owner:alice"
```

**Find open issues about a specific topic:**

```bash theme={null}
jjhub search issues "bookmark conflict" -s open
```

**Find code referencing a specific function:**

```bash theme={null}
jjhub search code "handle_landing_request"
```

**Find code in a specific language:**

```bash theme={null}
jjhub search code "import_refs language:rust"
```

***

## Rate Limiting

Search endpoints are rate-limited separately from the rest of the API:

| Type                            | Limit                   |
| ------------------------------- | ----------------------- |
| **Search (authenticated)**      | 30 requests per minute  |
| **Search (unauthenticated)**    | 10 requests per minute  |
| **General API (authenticated)** | 5,000 requests per hour |

When you exceed the search rate limit, the API returns `429 Too Many Requests` with standard rate limit headers:

```
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709726400
```

See the [Rate Limiting guide](/api-reference/rate-limiting) for more details.

## API Reference

| Method | Endpoint                         | Description                                      |
| ------ | -------------------------------- | ------------------------------------------------ |
| `GET`  | `/api/search/repositories?q=...` | Search repositories by name, description, topics |
| `GET`  | `/api/search/issues?q=...`       | Search issues by title, body, comments           |
| `GET`  | `/api/search/code?q=...`         | Search code by file contents                     |
| `GET`  | `/api/search/users?q=...`        | Search users by username, display name           |