Skip to main content

ado-search

Sync and search Azure DevOps work items and wiki pages locally for AI agents.

Install

pip install ado-search

Or from source:

pip install git+https://github.com/HurleySk/ado-search.git

Quick Start

# Configure (requires az login first)
ado-search init --org https://dev.azure.com/yourorg --project YourProject

# Pull data
ado-search sync

# Search
ado-search search "login bug"
ado-search search "auth" --type Bug --state Active
ado-search search "setup guide" --format paths

How It Works

  1. Sync pulls work items and wiki pages from Azure DevOps
    • Tries OData analytics first (fetches all items in one call — fast)
    • Falls back to az devops CLI if analytics isn't available
  2. Data is stored as sorted JSONL files — git-friendly, diffable, one file per entity type
  3. A SQLite FTS5 index is derived from the JSONL and auto-rebuilt when stale
  4. Agents search the index, then use show to render full content — minimal context

Git-Friendly Storage

Sync produces two text files that are safe to commit, push, and pull:

  • work-items.jsonl — one JSON object per line, sorted by ID
  • wiki-pages.jsonl — one JSON object per line, sorted by path

The SQLite index (index.db) is .gitignored — it auto-rebuilds from JSONL on first search or show.

Synced Fields

Each work item includes: id, title, type, state, area, iteration, assigned_to, tags, priority, parent_id, created, updated, description, acceptance_criteria, dev_notes (Custom.DevelopmentNotes), notes (Custom.Notes), story_points, state_history, attachments, and inline_images.

Story points are sourced from StoryPoints or Effort fields. State history tracks every state change (e.g., New → Active → Resolved → Closed) with date and author.

Attachments & Inline Images

When include_attachments = true in config, or --include-attachments is passed on the command line, sync/fetch downloads:

  • File attachments — stored in .ado-search/attachments/{work_item_id}/
  • Inline images — images embedded in Description/Acceptance Criteria HTML, stored in .ado-search/attachments/{work_item_id}/inline/
  • Comment images -- images pasted into work item comments (screenshots, diagrams), stored alongside other inline images. fetch --include-attachments automatically enables comment fetching to capture these.

Attachment filenames are indexed and searchable. Inline images are referenced as [image: path] in text output so agents can locate them. Downloads are incremental — existing files with correct size are skipped on re-sync.

Note: attachments require the WIQL/REST sync path (OData doesn't include relations), so OData fast path is skipped when attachments are enabled.

Use --include-attachments on fetch or sync for per-invocation attachment downloads without changing config:

# Fetch specific items with their attachments (also fetches comment images)
ado-search fetch 73541 --include-attachments

# One-time full sync with attachments
ado-search sync --include-attachments

Commands

Command Description
ado-search init Configure organization, project, and auth
ado-search sync Pull latest data from Azure DevOps (--full for complete re-fetch, --project to limit)
ado-search search "query" Full-text search with filters
ado-search show <id> Display full content of an item
ado-search create Create a new work item
ado-search update <id> Update an existing work item
ado-search add-comment <id> <text> Add a comment to a work item
ado-search edit-comment <id> <comment_id> <text> Replace the text of a comment
ado-search add-link <source> <target> Add a link between two work items
ado-search remove-link <source> <target> Remove a link between two work items
ado-search upload-attachment <id> <file> Upload a local file as an attachment to a work item
ado-search list-links <id> List links on a work item (live)
ado-search list-comments <id> List comments on a work item, with their ids (live)
ado-search get-fields <id> Print raw field values as JSON, HTML intact (live)
ado-search mentions List comments that @mention you, newest first (live)
ado-search test-plans List test plans with owner, area, iteration, dates (live)
ado-search test-suites <plan> Print a plan's suite tree: static, requirement or query suites (live)
ado-search test-cases <plan> <suite> List a suite's test cases with steps, shared steps and testers (live)
ado-search test-points <plan> <suite> List test points: configuration, tester, latest outcome (live)
ado-search test-runs List test runs with outcome counts, optionally for one plan (live)
ado-search test-results <run> List a run's results with linked bugs (live)
ado-search wiki-show [path] Print a wiki page's markdown, or list page paths (live, any project)
ado-search wiki-update <path> <file> Replace a wiki page from a local file, ETag-guarded (--dry-run diffs)
ado-search grep "pattern" Regex search across work item fields
ado-search children <parent_id> List children (or full tree) of a work item

Create & Update

Create and update work items directly from the CLI:

# Create a new bug
ado-search create --type Bug --title "Login button broken" --state New --priority 1

# Create with description and tags
ado-search create --type "User Story" --title "Add dark mode" \
  --description "Users want a dark theme option" \
  --tags "ui; theme" --story-points 5

# Create a child task under a parent work item
ado-search create --type Task --title "Subtask" --parent 62434

# Update a work item
ado-search update 12345 --state Active --assigned-to "user@example.com"

# Close as duplicate (--reason sets Microsoft.VSTS.Common.ResolvedReason)
ado-search update 67154 --state Closed --reason Duplicate

# Set arbitrary ADO fields (including custom fields)
ado-search create --type Task --title "Research" --field "Custom.Effort=3"
ado-search update 12345 --field "System.AreaPath=Project\Team" --field "Custom.Sprint=Sprint 5"

# Preview without writing
ado-search create --type Bug --title "Test" --dry-run

HTML Content from Files

Description, acceptance criteria, and comment text accept HTML. For multi-line content, use the @file convention to read from a file:

# Set description from an HTML file
ado-search create --type Bug --title "Rendering issue" --description @bug-details.html

# Update acceptance criteria from a file
ado-search update 12345 --acceptance-criteria @criteria.html

# Add a comment from a file
ado-search add-comment 12345 @review-notes.html

# Inline HTML still works
ado-search add-comment 12345 "<p>Looks good!</p>"

# @mentions are auto-resolved to ADO identity links
ado-search add-comment 12345 "Great work @John Smith (CTR), please review"

# Text that starts with an @mention needs @@ so it is not read as a file path
ado-search add-comment 12345 "@@Jane Doe, can you retest?"

# Refuse to post if any mention is unknown or ambiguous
ado-search add-comment 12345 "@@Jane Doe, can you retest?" --strict-mentions

# Skip mention resolution (post raw text as-is)
ado-search add-comment 12345 "@@not-a-user just a note" --no-mentions

# Escape a literal @ with @@
ado-search update 12345 --description "@@mention is not a file reference"

# Replace the text of a comment (ids come from list-comments)
ado-search edit-comment 12345 5335866 "@@Jane Doe, retest with build 2" --strict-mentions

edit-comment takes the same text forms and options as add-comment and replaces the whole comment.

@Display Name and @email patterns in comment text are resolved via the ADO Identity Picker API and replaced with mention HTML so the mentioned user receives a notification. A mention takes the longest run of up to five words that names exactly one person by whole words, so @Jane Doe (CTR), please tags Jane Doe and keeps , please, and @Jan never tags Janet. A first name shared by several people is reported as ambiguous and left as text. Existing mention anchors, <code>, and <pre> are left alone; write &#64; for a literal @ in the comment. Resolved, unresolved, and ambiguous mentions are reported on stderr.

After create/update/add-comment/edit-comment/add-link, the item is automatically re-fetched and merged into the local JSONL store so it appears in search immediately.

# Add a parent link
ado-search add-link 12345 67890 --type parent

# Add a related link with a comment
ado-search add-link 12345 67891 --type related --comment "See also this item"

# Link types: related, parent, child, duplicate, duplicate-of, depends-on, predecessor, successor
ado-search add-link 12345 67892 --type depends-on

# Use a raw ADO relation type
ado-search add-link 12345 67893 --type "System.LinkTypes.Related"

# Preview without creating
ado-search add-link 12345 67890 --type child --dry-run

# Remove a link
ado-search remove-link 12345 67890 --type parent

# List all links on a work item (live from ADO)
ado-search list-links 12345

# List all comments on a work item with their ids (live from ADO)
ado-search list-comments 12345

Raw Fields

show and the local store keep descriptions as plain text. get-fields reads the item live and prints raw values as JSON, so HTML can be edited and written back with update --description @file.html:

# Type, title, state, assignee, tags, story points, description, acceptance criteria
ado-search get-fields 12345

# Specific fields by reference name (repeatable)
ado-search get-fields 12345 --field System.Description --field Custom.Effort

# Write the JSON to a UTF-8 file instead of stdout
ado-search get-fields 12345 --out fields.json

Identity fields show the uniqueName (email); a field with no value is null. Nothing is written to ADO or the local store.

Mentions

mentions lists the comments that @mention you (the authenticated user), newest first, read live from ADO. Work items come from the WIQL macro @RecentMentions, so it covers the last 30 days:

# Every comment that mentions you (up to 50)
ado-search mentions

# Only comments created or modified after a UTC datetime, as JSON
ado-search mentions --since 2026-10-15T00:00:00Z --json

# Keep your own comments that mention you, and show up to 200
ado-search mentions --include-own --limit 200

Each record shows the work item id, title, state, type and assignee, then the comment id, author, created date (UTC) and plain text, with mentions written as @Name. A comment counts when one of its mention anchors carries your identity id; a comment with no mention anchors at all counts when its text holds @Your Name or @your email. Nothing is written to ADO or the local store.

Test Plans

Read Azure Test Plans live. Every command takes --project (default: the configured project), --json and --out FILE; nothing is written to ADO or the local store.

# Plans, optionally only active ones or those whose owner matches
ado-search test-plans --project "Wave 3" --owner "Rahman" --active

# A plan's suite tree; requirement suites show their work item, query suites their query
ado-search test-suites 76227

# Test cases in a suite: steps (action => expected), shared-step references, parameters, testers
ado-search test-cases 76227 76239
ado-search test-cases 76227 76239 --field System.Title --field Microsoft.VSTS.TCM.Steps --json

# Points (configuration, tester, latest outcome), runs, and one run's results with linked bugs
ado-search test-points 76227 76238
ado-search test-runs --plan 76472 --limit 50
ado-search test-results 31456

Paging follows x-ms-continuationtoken (plans, suites, cases, points) or $top/$skip (runs, results).

Wiki Pages

wiki-show and wiki-update work on single pages in any project, independent of sync. --wiki defaults to the project's only wiki.

# List page paths, or print one page's markdown
ado-search wiki-show --project "Reporting Sandbox"
ado-search wiki-show "/QA SOP" --project "Reporting Sandbox" --out qa-sop.md

# Show the diff against the live page, then replace it
ado-search wiki-update "/QA SOP" qa-sop.md --project "Reporting Sandbox" --dry-run
ado-search wiki-update "/QA SOP" qa-sop.md --project "Reporting Sandbox" --comment "Finalize QA SOP"

wiki-update reads the page first and sends its ETag with If-Match, so a page edited in between is refused (HTTP 412) instead of overwritten. The file is read as UTF-8; a BOM is dropped and line endings become LF. A missing page is an error unless --create is passed. Identical content makes no request.

With az-cli or az-powershell auth these commands call ADO through pwsh Invoke-WebRequest (with a token from az account get-access-token or Get-AzAccessToken), because az rest does not return response headers.

Configuration

Default sync includes Bug, User Story, Epic, and Feature work item types. To include Tasks or customize:

# .ado-search/config.toml
[sync]
work_item_types = ["Bug", "User Story", "Task", "Epic", "Feature"]
include_comments = false
include_attachments = false  # set to true to download file attachments and inline images

Multiple Projects

One data dir can hold several projects from the same organization:

[organization]
url = "https://dev.azure.com/yourorg"
project = "Alpha"              # default project for create/update/comments/links and wiki
projects = ["Alpha", "Beta"]   # or ["*"] for every project you can see
ado-search sync                    # syncs every configured project
ado-search sync --project Beta     # just one
ado-search search "timeout" --project Beta
ado-search grep "retry" --project Alpha

Each project keeps its own incremental watermark under [sync.last_sync_by_project]. Wiki pages are synced for the default project only.

Project names are matched case-insensitively, as in Azure DevOps. sync.area_paths entries apply to the project they start with (Alpha\Web filters Alpha only); a project with no matching entry syncs all its areas. work_item_types and states apply to every project, so list the types of every process you sync (e.g. both User Story and Product Backlog Item).

Auth Methods

  • az-cli (default): Uses az devops commands. Requires az login.
  • az-powershell: Uses Azure PowerShell + REST. Requires Connect-AzAccount.
  • pat: Uses a Personal Access Token via REST. For cross-cloud or service account scenarios.

Set via ado-search init --auth-method <method> or in config.toml.

# PAT example (token can also be set via ADO_PAT env var)
ado-search init --org https://dev.azure.com/yourorg --project YourProject --auth-method pat --pat <token>

Search Formats

ado-search search "query"                          # compact (default)
ado-search search "query" --format detail           # with description snippets
ado-search search "query" --format json             # machine-readable
ado-search search "query" --format paths            # file paths only (for agent piping)
ado-search search "query" --type Bug --state Active # filtered

Grep — Regex Pattern Matching

Search work items with regex patterns across fields:

# Find IP addresses anywhere in title/description/comments
ado-search grep '\d+\.\d+\.\d+\.\d+'

# Find "deprecated" only in comments, case-insensitive
ado-search grep -i 'deprecated' -f comments

# Find URL patterns in active bugs, brief output
ado-search grep 'https?://\S+' --type Bug --state Active --brief

# JSON output for scripting
ado-search grep 'TODO|FIXME' --format json

Default fields searched: title, description, dev_notes, notes, comments. Use --field / -f to scope to specific fields (title, description, acceptance_criteria, dev_notes, notes, comments, tags, assigned_to, area, iteration, state_history).

Metadata pre-filters (--type, --state, --area, --assigned-to, --tag) narrow candidates via SQLite indexes before the regex scan. Exit codes follow grep convention: 0 = matches found, 1 = no matches, 2 = error.

Children — Hierarchy Queries

Query work item parent-child hierarchy from local data:

# Show direct children of an epic
ado-search children 61123

# Full recursive tree (features, stories, tasks, ...)
ado-search children 61123 --recursive

# Indented tree view
ado-search children 61123 --recursive --format tree

# Filter to user stories only
ado-search children 61123 --recursive --type "User Story"

# Include closed date from state history
ado-search children 61123 --recursive --include-closed-date

# JSON for scripting
ado-search children 61123 --recursive --format json --include-closed-date

The children command queries the local SQLite index (no API calls). Use sync or fetch first to ensure data is current. Exit codes: 0 = children found, 1 = no children, 2 = parent not found.

Prerequisites

  • Python 3.10+
  • Azure CLI with azure-devops extension (az extension add --name azure-devops)
  • az login completed

Metadata

Release files for ado-search 1.19.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ado-search 1.19.0
File Size Uploaded Provenance Actions
ado_search-1.19.0.tar.gz 113.1 kB With provenance Details for ado_search-1.19.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ado-search 1.19.0
File Interpreter ABI Platform Actions
ado_search-1.19.0-py3-none-any.whl Python 3 none any Details for ado_search-1.19.0-py3-none-any.whl

Total release size: 189.1 kB

Release files / ado_search-1.19.0.tar.gz

Download URL ado_search-1.19.0.tar.gz
Size 113.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1e7f5d04765cd71e2f9ef69d99631246797604050331d2eab5f5303709920bb8
BLAKE2b-256 checksum
How to use checksums
5b3d473f8b68532c4770afb5083df170c751d6761de498733c9b2b7261f052dc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / ado_search-1.19.0-py3-none-any.whl

Download URL ado_search-1.19.0-py3-none-any.whl
Size 76.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e6b0f19266f11ed5661a881542c7de4e7e506b1fce7746f313699f9f6346ba68
BLAKE2b-256 checksum
How to use checksums
2156664ce236e8d48e3326e1c0de1e8943742fe34cc4f75f3c2f84c66f1901e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for ado-search 1.19.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ado_search-1.19.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.19.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page