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

# Query your workspace from the CLI

> Run research, search, lookup, and URL-resolve commands against your Unblocked workspace from the terminal

The `context-*` commands pull data from your Unblocked workspace — code, pull requests, issues, documentation, and messaging — and return it as plain JSON you can pipe into scripts, editors, CI jobs, and other automation. Every command returns a single JSON document on stdout.

<Note>
  These commands hit your Unblocked workspace, so they require an authenticated session (see [Authenticate](/unblocked-cli/cli-auth)) or an Unblocked API token in the environment.
</Note>

## When to use which command

| If you want to…                                               | Use                                            |
| ------------------------------------------------------------- | ---------------------------------------------- |
| Investigate a broad topic across every connected source       | [`context-research`](#context-research)        |
| Search one specific source type by keyword or phrase          | [`context-search-*`](#context-search-commands) |
| Retrieve issues or PRs by a structured natural-language query | [`context-query-*`](#context-query-commands)   |
| Fetch the content behind one or more URLs                     | [`context-get-urls`](#context-get-urls)        |

## `context-research`

Runs a multi-source research query across code, pull requests, docs, issues, and messaging. Returns synthesized context with citations. Use `--effort` to trade latency for thoroughness.

```bash theme={null}
unblocked context-research --query "<question>" [--instruction "..."] [--effort low|medium|high]
```

**Inputs**

| Flag            | Type                        | Required | Description                                               |
| --------------- | --------------------------- | -------- | --------------------------------------------------------- |
| `--query`       | string                      | yes      | The research question                                     |
| `--instruction` | string                      | no       | Extra instructions to steer the search                    |
| `--effort`      | `low` \| `medium` \| `high` | no       | Research effort level; higher is slower but more thorough |

**Output**

```json theme={null}
{
  "summary": "...",
  "sources": [
    { "title": "...", "url": "...", "content": "..." }
  ],
  "effort": "medium"
}
```

## `context-search` commands

The search commands run semantic search scoped to a single source type. They share the same inputs and output shape.

```bash theme={null}
unblocked context-search-code           --query "retry logic in billing service"
unblocked context-search-documentation  --query "deployment runbook"
unblocked context-search-issues         --query "flaky login test"
unblocked context-search-messages       --query "incident April 9"
unblocked context-search-prs            --query "migrate to React 18"
```

| Command                        | Searches                                                                   |
| ------------------------------ | -------------------------------------------------------------------------- |
| `context-search-code`          | Connected code sources for files, symbols, and snippets                    |
| `context-search-documentation` | Wikis, Notion, Confluence, and other documentation sources                 |
| `context-search-issues`        | Jira, Linear, GitHub Issues, and other issue trackers                      |
| `context-search-messages`      | Slack, Teams, and other messaging sources                                  |
| `context-search-prs`           | Pull requests and merge requests in your connected version control sources |

**Inputs**

| Flag            | Type   | Required | Description                                |
| --------------- | ------ | -------- | ------------------------------------------ |
| `--query`       | string | yes      | Free-text search query                     |
| `--instruction` | string | no       | Additional instruction to steer the search |

**Output**

```json theme={null}
{
  "sources": [
    {
      "title": "...",
      "url": "...",
      "content": "...",
      "sourceType": "code | documentation | issue | message | pull_request",
      "provider": "github | jira | slack | notion | ..."
    }
  ]
}
```

## `context-query` commands

Retrieve issues or pull requests using a structured natural-language query. Scope the results with `--projects` and `--user-name` for more precise matches.

```bash theme={null}
unblocked context-query-issues --query "open bugs assigned to Alex" \
  --projects ENG --projects BILLING --user-name alex
unblocked context-query-prs    --query "PRs merged last week by the platform team"
```

**Inputs**

| Flag          | Type   | Required | Description                                                                         |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `--query`     | string | yes      | Structured natural-language description of what to find                             |
| `--projects`  | array  | no       | Project names or keys to scope the search (repeat the flag or pass multiple values) |
| `--user-name` | string | no       | Name or username of a person referenced in the query                                |

**Output**

```json theme={null}
{
  "sources": [
    {
      "title": "...",
      "url": "...",
      "content": "{...raw record JSON...}",
      "sourceType": "issue | pull_request",
      "provider": "github | jira | linear | ..."
    }
  ]
}
```

The `content` field carries the raw record (issue fields, PR metadata, etc.) encoded as a JSON string so the shape can evolve per provider without breaking the envelope.

## `context-get-urls`

Fetch and return the content behind one or more URLs. Useful when you already have specific links — pull requests, issues, docs, message threads — and want to resolve them to full content.

```bash theme={null}
unblocked context-get-urls \
  --urls "https://github.com/unblocked/unblocked/pull/29384" \
  --urls "https://linear.app/unblocked/issue/ENG-243"
```

<Note>
  Pass `--urls` once per URL. Space-separated values after a single `--urls` will be rejected.
</Note>

**Inputs**

| Flag     | Type  | Required | Description                               |
| -------- | ----- | -------- | ----------------------------------------- |
| `--urls` | array | yes      | One or more URLs to retrieve content from |

**Output**

```json theme={null}
{
  "sources": [
    {
      "title": "...",
      "url": "...",
      "content": "...",
      "sourceType": "pull_request | issue | documentation | message"
    }
  ]
}
```

## Scripting tips

* Pipe the JSON output into `jq` to extract fields, for example: `unblocked context-search-prs --query "..." | jq '.sources[].url'`.
* Errors are returned as `{ "error": "CODE", "message": "..." }` with a non-zero exit code — check for the `error` key in scripts.
* For CI usage, authenticate with an API token (see [Headless auth](/unblocked-cli/cli-auth#headless-auth-with-an-api-token)).