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
- 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
- Data is stored as sorted JSONL files — git-friendly, diffable, one file per entity type
- A SQLite FTS5 index is derived from the JSONL and auto-rebuilt when stale
- Agents search the index, then use
showto 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 IDwiki-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-attachmentsautomatically 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 @ 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.
Links
# 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 devopscommands. Requiresaz 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-devopsextension (az extension add --name azure-devops) az logincompleted
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.