:::info Availability The Catalyst Assistant is not enabled by default. To have it turned on for your organization, reach out to your Diagrid representative. This quickstart assumes that has already happened. ::: # Quickstart: Catalyst Assistant In this quickstart, you'll ask the **Catalyst Assistant** your first question — once from the [Catalyst Cloud](https://docs.diagrid.io/operate/hosting/catalyst-cloud) web console, and once from your terminal. The assistant answers questions about your own Catalyst resources: projects, App IDs, components, workflow runs, agents, and MCP servers. An **App ID** is the identity Catalyst issues to each workload you run. You will learn how to: - Confirm the assistant is switched on for your organization, and what to do when it is not. - Open it in the console and ask a question about the page you're looking at. - Ask the same kind of question from a terminal with `diagrid chat`. - Read the answer: the line that states what the assistant may do, the tools it called, and the result. The assistant is **read-only**. It reads your resources and explains them. It does not create, change, rerun, terminate, or delete anything — those operations are not part of the tool set it was granted, so there is nothing for a phrasing of your question to unlock. ```mermaid --- title: How a question reaches the Catalyst Assistant --- flowchart TD CONSOLE(Catalyst console) CLI(diagrid chat) subgraph Catalyst ASSISTANT(Catalyst Assistant operated by Diagrid) TOOLS(Read-only Catalyst tools) end RESOURCES(Your projects, App IDs, workflow runs) CONSOLE--"your login"-->ASSISTANT CLI--"your login"-->ASSISTANT ASSISTANT-->TOOLS TOOLS-->RESOURCES ``` Both surfaces forward **your own login** to the assistant. It reads through your permissions, so it can reach exactly the projects you can reach and nothing more. One assistant serves a whole region rather than being spun up per person or per organization, and it forwards each caller's own login rather than holding one of its own. Diagrid operates the assistant and the model behind it for your organization, so there is no API key of yours to supply. ## 1. Prerequisites - A [Diagrid Catalyst account](https://catalyst.diagrid.io/) with at least one project that has some activity in it — a workflow run to look at makes the first question far more interesting. - **The Catalyst Assistant enabled for your organization by Diagrid.** This is not a setting you can switch on yourself, and there is no toggle for it anywhere in the console or the CLI. If you don't have it, ask your Diagrid contact to enable it for your organization. - **An organization-wide Catalyst role.** The permission that lets you call the assistant is granted by organization-wide roles only. If you were invited as a collaborator on a single project, you won't get it, even in an organization where the assistant is fully enabled — ask your organization admin for an organization-wide role. - The [Diagrid CLI](https://docs.diagrid.io/getting-started/install-cli), for step 3. ## 2. Ask a question in the console Sign in to the [Catalyst Cloud web console](https://catalyst.diagrid.io/). In the top bar, alongside the region, share, and account controls, select the assistant icon — its tooltip reads **Ask Catalyst Agent**. The panel opens beside the page you're on, and you can move it between **Pin to corner**, **Side panel**, and **Full screen**. :::note The console currently labels the panel **Catalyst Agent** while the CLI and this documentation call it the **Catalyst Assistant**. They are the same feature. ::: Type a question into the composer. Good first questions, all of which the assistant can answer from what it already knows about your organization: - `Which projects do I have, and what region is each in?` - `Which of my workflows in project have failing executions?` - `What changed in my organization recently?` - `Which regions do I have, and where are they?` Several console pages also carry an **Ask Catalyst Agent** button that opens the panel with the page already attached as context and a suggested question in the composer, so you don't retype identifiers. You'll find it on the workflows list, a workflow execution's detail page, the activity (audit) list, and the regions list. The suggested question is only ever placed in the composer for you to review or edit — nothing is sent until you send it. ### If the assistant isn't there The console shows the icon and the **Ask Catalyst Agent** buttons only when the assistant is actually available to you. When it isn't, it renders neither rather than offering a control that would explain itself only after a click. | What you see | What it means | What to do | | --- | --- | --- | | No assistant icon and no **Ask Catalyst Agent** buttons anywhere | Any one of: your organization isn't entitled, it's entitled but not switched on, the console isn't showing the assistant to your organization yet, or your own role doesn't reach it | Ask your Diagrid contact whether it's enabled for your organization. Run `diagrid chat` (step 3) — the CLI names which of the reasons applies | | A colleague sees it and you don't | Your role is scoped to a single project | Ask your organization admin for an organization-wide Catalyst role | | *"Catalyst Agent is being set up for your organization"* | Entitled and switched on, still being provisioned | Wait a few minutes and reload | ## 3. Ask the same question from the CLI The assistant verifies **you**, so the CLI needs a user login. An API key carries no user identity, and `diagrid chat` refuses one with a message saying exactly that. ```bash diagrid login ``` Then start the conversation: ```bash diagrid chat ``` `diagrid chat` is an interactive session: type a question, press Enter, and read the answer. `Ctrl+D` or `/exit` leaves. `/help` lists the rest of the in-chat commands, including `/new` to start a fresh conversation in place, `/cancel` to stop an answer that's already running, and `/mcp` to list the tools the assistant has loaded. Nothing about the conversation runs on your machine. The model, the tools, and the system prompt are all served by the assistant, which is why there is no API key to configure and no local process to keep alive. If the assistant isn't available to you, `diagrid chat` says which of the reasons applies rather than failing with a transport error — for example: ``` the Catalyst Assistant is not included in the plan for acme — contact Diagrid to have it added ``` ``` the Catalyst Assistant identifies you by your own login, which an API key does not carry — run `diagrid login` and try again ``` ## 4. Read the answer Every session opens with a line stating what the assistant may do on your behalf, because that's set per organization rather than being the same everywhere: ``` ─ Catalyst Assistant · read-only · sharing metadata only ``` - **read-only** is what the assistant may do. This is the only mode available today. - **sharing metadata only** is how much of a response it may see: resource names, statuses, and timestamps, but not workflow inputs and outputs or other application payloads. This is the default for a newly enabled organization, and it's the conservative one — an organization that never chooses a level never sends payloads to the model by omission. An example of what the CLI prints for a first question, with the tool activity it shows by default. The prompt and tool markers and the tool names are what you'll see; the workflow names, run counts, and step names below are illustrative: ``` ❯ Which of my workflows in project orders have failing executions? ⚙ calling catalyst_whoami(…) ⚙ calling catalyst_list_workflows(…) ⚙ calling catalyst_list_workflow_runs(…) ◆ Catalyst Assistant Two workflows in `orders` have failed runs in the last day: - `client_onboarding` — 4 failed of 61. The most recent failed at the `verify_identity` step. - `payment_capture` — 1 failed of 340, at `charge_card`. Ask me about a specific run and I can show you where in its graph it stopped. ``` A good answer has three marks: it names real resources of yours rather than generic advice, it shows which read-only tools produced the facts, and it offers the next question rather than an action. Pass `--show-tools=false` to hide the tool lines and read the conversation on its own. The most useful follow-up is a single run. Ask `Where is run stuck?` and the assistant reads that execution's graph — the step it's on or failed at. That graph has no CLI equivalent, which makes it the clearest thing the assistant does that you cannot quickly do yourself. At the `metadata` level, one tool refuses rather than answering: reading application log lines. A log line is whatever your application printed, so there is no metadata-only version of one, and the assistant says so instead of returning an empty log that reads like a missing file. If your team needs the assistant to read logs and workflow payloads, ask your Diagrid contact about raising your organization's data-sharing level. ## 5. Know what it won't answer The assistant is granted a fixed set of read-only Catalyst tools. Outside that set it has nothing to call: | Area | What it can read | | --- | --- | | Account | Your organization, its projects, and its regions | | Projects | Each project's region, managed services, and readiness | | App IDs | Endpoints, readiness, and any connected local tunnel | | Components | Type, version, readiness, and setting *names* — inline values are withheld | | Workflows | Definitions, their activity graphs, runs, and one run's execution graph | | Agents and MCP servers | What's registered, and the tools a server advertises | | Access policies | Which callers are granted which operations | | Observability | Request and error rates, quota consumption, and application logs when your data-sharing level allows them | | Audit | Who changed what, and when, across the organization | | Templates and regions | The templates you can start from, and one region's type, status, and whether it's connected | It holds no write tools at all, and billing, invoices, payment methods, service-account keys, and workload-identity tokens are left out of the surface entirely. This is a different thing from [connecting an AI coding assistant to Catalyst](https://docs.diagrid.io/develop/local-development/assistant-mcp). That runs on your laptop, under your own `diagrid login`, and does include workflow-lifecycle write tools. The Catalyst Assistant is hosted by Diagrid, shared by your whole organization, and read-only. ## Summary In this quickstart you: - Confirmed the assistant is enabled for your organization, and learned which message points at which of the reasons it may not be. - Opened it in the console and asked a question about your own resources, with the page you were on attached as context. - Ran the same conversation from a terminal with `diagrid login` and `diagrid chat`. - Read the posture line, the tool calls behind an answer, and what the default data-sharing level does and doesn't let the assistant see. ## Next steps - Read [Catalyst Assistant](https://docs.diagrid.io/concepts/catalyst-assistant) for how it's operated, how your permissions bound it, and what the data-sharing level controls. - Work through [Ask the Catalyst Assistant](https://docs.diagrid.io/develop/agents/catalyst-assistant) for the questions it answers best, and the ones it deliberately cannot. - Give an assistant on your own machine a curated set of Catalyst tools with [Connect an AI coding assistant to Catalyst](https://docs.diagrid.io/develop/local-development/assistant-mcp). - Look up every flag in the [`diagrid chat`](https://docs.diagrid.io/references/catalyst/cli-reference/chat) reference.