Arete documentation

Catalog and Descriptors

Finding something in Arete happens in two steps. First you search, to see what might fit. Then you inspect one exact result, to see what it really offers. Your agent normally does both for you. This page shows the commands behind each step, which is handy when you want to check the agent’s work or script it yourself.

Three things are involved:

the catalog helps an agent find programs and stacks that match what you want to do;
a descriptor is the exact spec sheet for one installable package, including how it can be delivered; and
generated code supplies the final names and types in your language.

Search the catalog

Describe the job in your own words with --query, then narrow the results with filters:

a4 explore catalog --query "monitor swaps" --json
a4 explore catalog --query "manage a multisig" --kind program --json
a4 explore catalog --category defi --mode subscribe --json
a4 explore catalog --kind program --mode read --target typescript --json

Available filters:

Filter	Meaning
`--query`	Free-text intent
`--concept`	Exact catalog concept slug
`--category`	Exact category slug
`--kind`	`program` or `stack`
`--mode`	`read`, `build`, or `subscribe`
`--target`	Verified `typescript`, `rust`, or `python` SDK output
`--limit`, `--cursor`	Bounded pagination

Search results are brief by default: each keeps its kind, slug, name, version, protocol, summary, modes, SDK targets and delivery status, ten to a page. Brief JSON adds a top-level hint that names --full (every field, including identity hashes and release notes), --fields, and the next --cursor when there is one. Without filters, a4 explore catalog prints an overview of the first programs and stacks.

Program, stack and protocol slugs often differ for the same thing (protocol jurassic, stack jurassic-launchpad, program jurassic-fi-token-sale), so results link them:

programs (stacks): the programs the stack composes, as [{slug, programId}]. Install a slug to build transactions for it.
stacks (programs): the stacks composing the program, as [{slug, live}]. Install a live slug to stream it.
installName (programs): a second name the program installs under, when it differs from the slug. Both install the same package.
protocols (the page): one entry per result protocol, {protocol, stacks, programs}, listing every stack and program of that protocol, including ones on other pages or excluded by --kind. On a search narrowed by a query, concept, category, mode or target, each has matched: whether the search returns it. A protocol’s other entries are listed with matched: false (a launchpad search lists a protocol’s AMM stacks unmatched), so whether a protocol is live for the question comes from its matched stacks only. Text output lists them under not matched.

Cite the slug of the kind you use: the stack to stream, the program to build. Two more keys are derived:

live (stacks only): true when the stack has a hosted stream you can subscribe to now, which is when its modes include subscribe; false when it is definition-only. A definition-only stack still installs as a typed SDK with its Program SDKs (build transactions, read accounts); it streams once you deploy it yourself. --mode subscribe returns only live stacks. Programs have no stream, so they carry no live.
related: only on results the server sent no programs/stacks for (older catalog versions): the other results on the same page that share the entry’s protocol, as kind:slug.

A page continued with --cursor after the catalog changed carries catalogChanged: true: entries may be skipped or repeated, so search again without --cursor when you need an exact listing.

a4 explore catalog --query "monitor swaps" --json
a4 explore catalog --query "monitor swaps" --full --json
a4 explore catalog --query "monitor swaps" --fields slug,kind,delivery.status
a4 know search --query "monitor swaps" --brief

List canonical concept and category slugs (with names; --full adds descriptions and synonyms) before using exact filters:

a4 explore catalog --vocabulary --json

The catalog is live and keeps changing. Don’t keep a hand-written “available stacks” list in your application instructions, because it will go stale.

Inspect an exact result

a4 explore catalog program <slug> --json
a4 explore catalog stack <slug> --json

The descriptor is pinned to the very package that a4 install will consume. Treat it as a single contract. It is not a menu to pick and mix from.

A program descriptor can include:

program and release identities;
accounts, instructions, events, and types;
hosted Program Read availability;
supported SDK targets; and
the exact install command.

A stack descriptor can include:

its exact composition identity;
selected live views and the Program SDKs for the programs they read from;
independent live, Program Read, chain, and transaction bindings;
authentication requirements;
supported SDK targets; and
the exact install command.

If an identity or connection detail you need is missing, treat the package as unavailable for that operation. Don’t fall back to “latest,” guess an endpoint, or combine parts from two descriptor versions.

Compatibility discovery commands

These commands remain useful for direct surveys and scripts:

a4 explore --json
a4 explore programs --json
a4 explore stack <ref> --json
a4 explore program <ref> --json

a4 explore stack and a4 explore program print a compact summary of a few KB by default. Ask for the part you need next:

a4 explore stack <ref> --views <Entity>/<view>,<Entity>/<view> --json
a4 explore stack <ref> --operation <operation> --json
a4 explore program <ref> --operation <operation> --json
a4 explore program <ref> --section instructions --json
a4 explore stack <ref> --full --json     # identity hashes, every auth surface, SDK metadata
a4 explore program <ref> --full --json   # the IDL-level dump

The stack summary says whether the stack is live, and lists its entities and views, the token-amount fields with their units (amountFields), the read.* helpers its SDK extension adds (such as ORE’s read.currentRound()), its Program SDKs, stream endpoints, stream auth and the install command. The program summary lists instructions and accounts with the first line of their docs, the PDAs the program derives with their seeds, its SDK operations and transports. --operation shows one operation, and on a stack it searches the stack’s Program SDKs. Exploring a definition-only stack prints what you can do with it instead of failing. See a4 explore for every option.

For a stack published in the catalog, entities and views also carry a curated summary, and the fields in --views a description. Read them before choosing fields: they say, for example, which of two similar fields a live UI should show. To see every field of one entity with its description, run a4 explore stack <ref> <Entity> --json.

Prefer a4 explore catalog when starting from intent or filtering by capability mode. Prefer the explicit stack and program forms over legacy positional stack syntax in new automation.

Curated knowledge

The catalog tells you what exists. The knowledge layer adds context that people have reviewed: background on each protocol, the role each program plays, which concepts are covered, and step-by-step recipes. Where your installed CLI exposes it:

a4 know search --query "monitor swaps" --json
a4 know protocol <slug> --json
a4 know program <slug> --section surface --json
a4 know recipe <slug> --json

Use it to understand why a program fits what you’re trying to do. Then go back to the exact catalog descriptor before installing or connecting. A missing recipe means the workflow hasn’t been documented yet. It doesn’t automatically mean the workflow is impossible.

Knowledge routes may require a4 auth signup or a4 auth login.

Install exactly what you inspected

Prefer the descriptor’s reported command:

a4 install program <slug> --ts
a4 install stack <slug> --ts

Install a stack when you need live views, with or without transactions. It includes the Program SDK for each program its views read from, the same one a4 install program gives you, so its operations need no separate program install. Install a program on its own when you only need reads and transactions.

A saved install updates arete.toml, resolves arete.lock, and generates code for the complete set of dependencies. Use --no-save only when you deliberately want a one-off output.

Machine-readable output

Agents and scripts should pass --json. The response carries a schema version and may gain fields over time. Read the fields you need and leave unknown ones intact. Don’t rebuild a response from the examples on this page.

When CLI help and prose differ, current a4 explore --help, the JSON response, and generated types win.