repos.list() - Mesa Docs

List repositories using cursor pagination. Required scope: read

const repos = await mesa.repos.list({ limit: 50 });

for (const repo of repos.repos) {
  console.log(repo.name, repo.default_bookmark, repo.head_change_id);
}

Options

string | undefined

Organization override.

string | undefined

Opaque pagination cursor from a previous response.

number | undefined

Maximum number of repositories to return. The server maximum is 100.

RepoTagFilter | string | undefined

Filter results by repository tags. See Tag Filters below.

Tag Filters

Filter the repository list by the tags on each repository. Pass an object where each key is a tag name:

await mesa.repos.list({
  tags: {
    kind: 'memory', // kind equals "memory"
    environment: 'prod', // environment equals "prod"
    region: ['us-east-1', 'us-west-2'], // region is either value
  },
});

A repository matches when every key matches: multiple keys in one object are implicitly combined with the logical $and operator. The filter above is equivalent to:

await mesa.repos.list({
  tags: {
    $and: [{ kind: 'memory' }, { environment: 'prod' }, { region: ['us-east-1', 'us-west-2'] }],
  },
});

Combine $and, $or, and $not to build more complex queries:

await mesa.repos.list({
  tags: {
    $and: [
      { workload: { $in: ['sync', 'index'] } },
      { $or: [{ environment: 'prod' }, { environment: 'staging' }] },
      { $not: { lifecycle: 'archived' } }, // excludes archived repos
    ],
  },
});

Operator names start with $ and are case-insensitive ($and, $AND, and $AnD are equivalent). The $ prefix is reserved for operators, so a tag name can never start with $ — but plain and, or, and not are ordinary tag names.

Value Operators

Tag values match exactly by default. Wrap the value in an operator object for other comparisons:

Operator	Example	Matches
`$eq`	`{ environment: { $eq: 'prod' } }`	Exact tag value
`$in`	`{ region: { $in: ['us-east-1', 'us-west-2'] } }`	Any listed tag value
`$contains`	`{ owner: { $contains: 'agent' } }`	Tag value contains literal text
`$starts_with`	`{ region: { $starts_with: 'us-' } }`	Tag value starts with literal text
`$ends_with`	`{ owner: { $ends_with: '@platform' } }`	Tag value ends with literal text
`$exists`	`{ archived: { $exists: false } }`	Tag key presence or absence

$exists checks only whether the tag key is present, regardless of its value. To match a specific value, use an exact match instead.

await mesa.repos.list({
  tags: {
    archived: { $exists: false },
    lifecycle: { $eq: 'active' },
  },
});

Complex Composition

This example selects active production-like skill or memory repos that are owned by platform teams and located in US regions:

const result = await mesa.repos.list({
  tags: {
    $and: [
      { environment: { $in: ['prod', 'staging'] } },
      { region: { $starts_with: 'us-' } },
      {
        $or: [
          { kind: 'skill', owner: { $contains: 'agent' } },
          { kind: 'memory', owner: { $ends_with: '@platform' } },
        ],
      },
      { $not: { lifecycle: 'archived' } },
      { archived: { $exists: false } },
    ],
  },
});

Matching semantics:

Everything is case-insensitive: operator names, tag keys (normalized to lowercase), and tag value comparisons.
$and matches when all child filters match, $or when any child matches, and $not negates its child filter.
$contains, $starts_with, and $ends_with match literal text — %, _, and \ in the search text are escaped, not treated as wildcards.
Filters are limited to depth 8, 64 total clauses, 32 items in $and, $or, and $in arrays, and 256 characters per tag key or value.

The TypeScript SDK serializes filter objects and sends them to the API. Invalid filters return 400 INVALID_REQUEST from the server. For direct REST calls, pass the filter as a JSON-encoded string in the tags query parameter:

const tags = JSON.stringify({
  $and: [{ environment: 'prod' }, { $not: { lifecycle: 'archived' } }],
});

await fetch(`/v1/acme/repos?tags=${encodeURIComponent(tags)}`);

Legacy comma-separated string filters ('environment:prod,team:core') are still accepted but deprecated. Pass the result directly to fs.mount() to mount the filtered set of repositories:

const { repos } = await mesa.repos.list({
  tags: { $and: [{ environment: 'prod' }, { kind: 'skill' }] },
});

const fs = await mesa.fs.mount({
  repos,
  authors: [{ name: 'Workspace Agent', email: 'agent@example.com' }],
});

Response

string | null

Cursor for the next page, or null when no more results remain.

boolean

Whether another page of results is available.

Repo[]

Repository objects.

Repo

string

Repository ID.

string

Organization slug.

string

Repository name.

string

Default bookmark name.

string

Current change ID at the default bookmark tip.

UpstreamConfig | null

Configured upstream remote, or null when no upstream is configured.

string

Creation time.

Record<string, string>

Repository tags.

UpstreamConfig

string

Upstream Git remote URL.

'token' | 'username_password' | null

Stored upstream authentication kind, or null when the upstream is public.

​Options

​Tag Filters

​Value Operators

​Complex Composition

​Response

​Repo

​UpstreamConfig

Options

Tag Filters

Value Operators

Complex Composition

Response

Repo

UpstreamConfig