Query your workspace from the CLI

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.

These commands hit your Unblocked workspace, so they require an authenticated session (see Authenticate) or an Unblocked API token in the environment.

When to use which command

If you want to…	Use
Investigate a broad topic across every connected source	`context-research`
Search one specific source type by keyword or phrase	`context-search-*`
Retrieve issues or PRs by a structured natural-language query	`context-query-*`
Fetch the content behind one or more URLs	`context-get-urls`
Get a repository’s coding rules	`context-get-rules`

`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.

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

{
  "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.

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

{
  "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.

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

{
  "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.

unblocked context-get-urls \
  --urls "https://github.com/unblocked/unblocked/pull/29384" \
  --urls "https://linear.app/unblocked/issue/ENG-243"

Pass --urls once per URL. Space-separated values after a single --urls will be rejected.

Inputs

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

Output

{
  "sources": [
    {
      "title": "...",
      "url": "...",
      "content": "...",
      "sourceType": "pull_request | issue | documentation | message"
    }
  ]
}

`context-get-rules`

Returns the coding rules Unblocked extracts from a repository’s instruction files, such as AGENTS.md, CLAUDE.md, and .cursorrules. Rules are sorted by severity, must first, and the command returns the first 20 by default. Pass --task and --paths to get the rules that apply to your files, and --max-rules to get more.

unblocked context-get-rules --repo-name owner/repo --task code-review --paths src/app.ts src/api/client.ts

Inputs

Flag	Type	Required	Description
`--repo-name`	string	yes	The repository, in `owner/repo` form
`--task`	string	no	`code-review`, `code-generation`, or `code-questions`
`--language`	string	no	A language, such as `typescript` or `go`
`--paths`	array	no	Repo-relative paths of the files you’re working on. Rules from a nested instruction file, such as `<dir>/AGENTS.md`, are returned only when a path is inside `<dir>/`. Rules from root instruction files always apply
`--max-rules`	integer	no	How many rules to return, highest severity first. Must be a positive integer. Defaults to 20
`--rule-id`	string	no	Returns one rule by its ID

Output Each rule is one source. content holds its description, severity, category, tasks, languages, and source file, and url links to the source file. totalMatched is how many rules matched before the limit. When it is larger than the number of sources, the output also includes a note that says how to get more.

{
  "sources": [
    {
      "title": "...",
      "url": "...",
      "content": "...",
      "sourceType": "rules"
    }
  ],
  "totalMatched": 127,
  "note": "Showing 20 of 127 rules, highest severity first. Pass filters (--paths, --task, --language) to narrow or a larger --max-rules to get more."
}

An empty sources array means Unblocked found no rules for the repository, or none matched the filters. A repository that doesn’t exist and one you can’t access both return a not-found error.

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 authentication.

Getting Started with Unblocked

Product Guides

Using Unblocked

Personal Settings

Team Settings

Billing

Data Sources

Query your workspace from the CLI

When to use which command

`context-research`

`context-search` commands

`context-query` commands

`context-get-urls`

`context-get-rules`

Scripting tips

​When to use which command

​context-research

​context-search commands

​context-query commands

​context-get-urls

​context-get-rules

​Scripting tips

When to use which command

`context-research`

`context-search` commands

`context-query` commands

`context-get-urls`

`context-get-rules`

Scripting tips