gitlore/docs/command-surface-analysis/01-entity-commands.md

Entity Query Commands

Reference for: issues, mrs, notes, search, count

---

issues (alias: issue)

List or show issues from local database.

Flag	Type	Default	Purpose
[IID]	positional	—	Omit to list, provide to show detail
-n, --limit	int	50	Max results
--fields	string	—	Select output columns (preset: minimal)
-s, --state	enum	—	opened|closed|all
-p, --project	string	—	Filter by project (fuzzy)
-a, --author	string	—	Filter by author username
-A, --assignee	string	—	Filter by assignee username
-l, --label	string[]	—	Filter by labels (AND logic, repeatable)
-m, --milestone	string	—	Filter by milestone title
--status	string[]	—	Filter by work-item status (COLLATE NOCASE, OR logic)
--since	duration/date	—	Filter by created date (7d, 2w, YYYY-MM-DD)
--due-before	date	—	Filter by due date
--has-due	flag	—	Show only issues with due dates
--sort	enum	updated	updated|created|iid
--asc	flag	—	Sort ascending
-o, --open	flag	—	Open first match in browser

DB tables: issues, projects, issue_assignees, issue_labels, labels Detail mode adds: discussions, notes, entity_references (closing MRs)

Robot Output (list mode)

{
  "ok": true,
  "data": {
    "issues": [
      {
        "iid": 42, "title": "Fix auth", "state": "opened",
        "author_username": "jdoe", "labels": ["backend"],
        "assignees": ["jdoe"], "discussion_count": 3,
        "unresolved_count": 1, "created_at_iso": "...",
        "updated_at_iso": "...", "web_url": "...",
        "project_path": "group/repo",
        "status_name": "In progress"
      }
    ],
    "total_count": 150, "showing": 50
  },
  "meta": { "elapsed_ms": 40, "available_statuses": ["Open", "In progress", "Closed"] }
}

Robot Output (detail mode — issues <IID>)

{
  "ok": true,
  "data": {
    "id": 12345, "iid": 42, "title": "Fix auth",
    "description": "Full markdown body...",
    "state": "opened", "author_username": "jdoe",
    "created_at": "...", "updated_at": "...", "closed_at": null,
    "confidential": false, "web_url": "...", "project_path": "group/repo",
    "references_full": "group/repo#42",
    "labels": ["backend"], "assignees": ["jdoe"],
    "due_date": null, "milestone": null,
    "user_notes_count": 5, "merge_requests_count": 1,
    "closing_merge_requests": [
      { "iid": 99, "title": "Refactor auth", "state": "merged", "web_url": "..." }
    ],
    "discussions": [
      {
        "notes": [
          { "author_username": "jdoe", "body": "...", "created_at": "...", "is_system": false }
        ],
        "individual_note": false
      }
    ],
    "status_name": "In progress", "status_color": "#1068bf"
  }
}

Minimal preset: iid, title, state, updated_at_iso

---

mrs (aliases: mr, merge-request, merge-requests)

List or show merge requests.

Flag	Type	Default	Purpose
[IID]	positional	—	Omit to list, provide to show detail
-n, --limit	int	50	Max results
--fields	string	—	Select output columns (preset: minimal)
-s, --state	enum	—	opened|merged|closed|locked|all
-p, --project	string	—	Filter by project
-a, --author	string	—	Filter by author
-A, --assignee	string	—	Filter by assignee
-r, --reviewer	string	—	Filter by reviewer
-l, --label	string[]	—	Filter by labels (AND)
--since	duration/date	—	Filter by created date
-d, --draft	flag	—	Draft MRs only
-D, --no-draft	flag	—	Exclude drafts
--target	string	—	Filter by target branch
--source	string	—	Filter by source branch
--sort	enum	updated	updated|created|iid
--asc	flag	—	Sort ascending
-o, --open	flag	—	Open in browser

DB tables: merge_requests, projects, mr_reviewers, mr_labels, labels, mr_assignees Detail mode adds: discussions, notes, mr_diffs

Robot Output (list mode)

{
  "ok": true,
  "data": {
    "mrs": [
      {
        "iid": 99, "title": "Refactor auth", "state": "merged",
        "draft": false, "author_username": "jdoe",
        "source_branch": "feat/auth", "target_branch": "main",
        "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
        "discussion_count": 5, "unresolved_count": 0,
        "created_at_iso": "...", "updated_at_iso": "...",
        "web_url": "...", "project_path": "group/repo"
      }
    ],
    "total_count": 500, "showing": 50
  }
}

Robot Output (detail mode — mrs <IID>)

{
  "ok": true,
  "data": {
    "id": 67890, "iid": 99, "title": "Refactor auth",
    "description": "Full markdown body...",
    "state": "merged", "draft": false, "author_username": "jdoe",
    "source_branch": "feat/auth", "target_branch": "main",
    "created_at": "...", "updated_at": "...",
    "merged_at": "...", "closed_at": null,
    "web_url": "...", "project_path": "group/repo",
    "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
    "discussions": [
      {
        "notes": [
          {
            "author_username": "reviewer", "body": "...",
            "created_at": "...", "is_system": false,
            "position": { "new_path": "src/auth.rs", "new_line": 42 }
          }
        ],
        "individual_note": false
      }
    ]
  }
}

Minimal preset: iid, title, state, updated_at_iso

---

notes (alias: note)

List discussion notes/comments with fine-grained filters.

Flag	Type	Default	Purpose
-n, --limit	int	50	Max results
--fields	string	—	Preset: minimal
-a, --author	string	—	Filter by author
--note-type	enum	—	DiffNote|DiscussionNote
--contains	string	—	Body text substring filter
--note-id	int	—	Internal note ID
--gitlab-note-id	int	—	GitLab note ID
--discussion-id	string	—	Discussion ID filter
--include-system	flag	—	Include system notes
--for-issue	int	—	Notes on specific issue (requires -p)
--for-mr	int	—	Notes on specific MR (requires -p)
-p, --project	string	—	Scope to project
--since	duration/date	—	Created after
--until	date	—	Created before (inclusive)
--path	string	—	File path filter (exact or prefix with /)
--resolution	enum	—	any|unresolved|resolved
--sort	enum	created	created|updated
--asc	flag	—	Sort ascending
--open	flag	—	Open in browser

DB tables: notes, discussions, projects, issues, merge_requests

Robot Output

{
  "ok": true,
  "data": {
    "notes": [
      {
        "id": 1234, "gitlab_id": 56789,
        "author_username": "reviewer", "body": "...",
        "note_type": "DiffNote", "is_system": false,
        "created_at_iso": "...", "updated_at_iso": "...",
        "position_new_path": "src/auth.rs", "position_new_line": 42,
        "resolvable": true, "resolved": false,
        "noteable_type": "MergeRequest", "parent_iid": 99,
        "parent_title": "Refactor auth", "project_path": "group/repo"
      }
    ],
    "total_count": 1000, "showing": 50
  }
}

Minimal preset: id, author_username, body, created_at_iso

---

search (aliases: find, query)

Semantic + full-text search across indexed documents.

Flag	Type	Default	Purpose
<QUERY>	positional	required	Search query string
--mode	enum	hybrid	lexical|hybrid|semantic
--type	enum	—	issue|mr|discussion|note
--author	string	—	Filter by author
-p, --project	string	—	Scope to project
--label	string[]	—	Filter by labels (AND)
--path	string	—	File path filter
--since	duration/date	—	Created after
--updated-since	duration/date	—	Updated after
-n, --limit	int	20	Max results (max: 100)
--fields	string	—	Preset: minimal
--explain	flag	—	Show ranking breakdown
--fts-mode	enum	safe	safe|raw

DB tables: documents, documents_fts (FTS5), embeddings (vec0), document_labels, document_paths, projects

Search modes:

• lexical — FTS5 with BM25 ranking (fastest, no Ollama needed)
• hybrid — RRF combination of lexical + semantic (default)
• semantic — Vector similarity only (requires Ollama)

Robot Output

{
  "ok": true,
  "data": {
    "query": "authentication bug",
    "mode": "hybrid",
    "total_results": 15,
    "results": [
      {
        "document_id": 1234, "source_type": "issue",
        "title": "Fix SSO auth", "url": "...",
        "author": "jdoe", "project_path": "group/repo",
        "labels": ["auth"], "paths": ["src/auth/"],
        "snippet": "...matching text...",
        "score": 0.85,
        "explain": { "vector_rank": 2, "fts_rank": 1, "rrf_score": 0.85 }
      }
    ],
    "warnings": []
  }
}

Minimal preset: document_id, title, source_type, score

---

count

Count entities in local database.

Flag	Type	Default	Purpose
<ENTITY>	positional	required	issues|mrs|discussions|notes|events|references
-f, --for	enum	—	Parent type: issue|mr

DB tables: Conditional aggregation on entity tables

Robot Output

{
  "ok": true,
  "data": {
    "entity": "merge_requests",
    "count": 1234,
    "system_excluded": 5000,
    "breakdown": { "opened": 100, "closed": 50, "merged": 1084 }
  }
}