Skip to main content
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 sourcecontext-research
Search one specific source type by keyword or phrasecontext-search-*
Retrieve issues or PRs by a structured natural-language querycontext-query-*
Fetch the content behind one or more URLscontext-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. 
unblocked context-research --query "<question>" [--instruction "..."] [--effort low|medium|high]
Inputs
FlagTypeRequiredDescription
--querystringyesThe research question
--instructionstringnoExtra instructions to steer the search
--effortlow | medium | highnoResearch 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"
CommandSearches
context-search-codeConnected code sources for files, symbols, and snippets
context-search-documentationWikis, Notion, Confluence, and other documentation sources
context-search-issuesJira, Linear, GitHub Issues, and other issue trackers
context-search-messagesSlack, Teams, and other messaging sources
context-search-prsPull requests and merge requests in your connected version control sources
Inputs
FlagTypeRequiredDescription
--querystringyesFree-text search query
--instructionstringnoAdditional 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
FlagTypeRequiredDescription
--querystringyesStructured natural-language description of what to find
--projectsarraynoProject names or keys to scope the search (repeat the flag or pass multiple values)
--user-namestringnoName 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
FlagTypeRequiredDescription
--urlsarrayyesOne or more URLs to retrieve content from
Output 
{
  "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).