/catalyst-basics

Catalyst Project Basics — Reference

Project Constraints (Know Before Creating)

• First project must be created from the console — catalyst init can create subsequent projects from the CLI, but the very first one must be done at https://console.catalyst.zoho.com.
• Project name rules — alphanumeric, underscores (_), and hyphens (-) only. No spaces or special characters.
• 50-project limit per account — contact support@zohocatalyst.com to request an increase.
• Console URL differs by data center:
  • US and others: https://console.catalyst.zoho.com/baas/index
  • EU: https://console.catalyst.zoho.eu/baas/index
  • IN: https://console.catalyst.zoho.in/baas/index

"Start Exploring" Requirement

Before any service can be deployed to Production, a user must click "Start Exploring" for that service in the Catalyst console. This is a one-time activation per service per project — without it, deploying that service to Production is blocked. This applies to all services: Slate, Functions, AppSail, Data Store, etc.

Project Directory Structure

When catalyst init is run, a standard project layout is created:

my-catalyst-project/
├── catalyst.json                 # Auto-generated project config — NEVER create manually
├── .catalystrc                   # Auto-generated project identity — NEVER create manually
├── functions/                    # All server-side functions
│   └── function_name/
│       ├── index.js              # Entry point (Node.js)
│       ├── catalyst-config.json  # Function-specific config
│       ├── package.json
│       └── node_modules/
├── my-slate-app/                 # Slate frontend (PREFERRED for new projects)
│   └── catalyst-config.json
├── client/                       # ⚠️ LEGACY — use Slate instead
└── appsail/                      # AppSail services (optional)
    ├── app.js
    ├── catalyst-config.json
    └── package.json

Key rules:

• The functions/ directory name is fixed and cannot be renamed.
• Each function must be in its own subdirectory under functions/.
• For frontends, always use Slate — do NOT select "Client" during catalyst init, it is legacy.
• catalyst.json and .catalystrc are auto-generated — NEVER create them manually.

catalyst.json

Holds deployment configuration. Auto-generated by the CLI.

{
  "functions": {
    "targets": ["myFunction1", "myFunction2"],
    "ignore": [],
    "source": "functions"
  },
  "appsail": {
    "targets": ["my-appsail-service"],
    "source": "appsail"
  },
  "slate": [
    { "name": "my-frontend", "source": "/absolute/path/to/client" }
  ]
}

• The functions block must include targets, ignore, and source or CLI errors.
• Slate source must be an absolute path.

.catalystrc — Project Identity File

{
  "project_id": "YOUR_PROJECT_ID",
  "project_domain": "your-app-YOUR_ENV_ID.development",
  "env_id": "YOUR_ENV_ID",
  "timezone": "Asia/Kolkata"
}

Contains project_id, env_id, project_domain, and timezone. If missing, catalyst deploy fails.

catalyst-config.json for Functions

{
  "deployment": {
    "name": "my_function",
    "type": "advancedio",
    "stack": "node20",
    "env_variables": {}
  },
  "execution": {
    "main": "index.js"
  }
}

Valid type values (use exactly as shown — do not change this after function creation):

browserlogic — NOT browselogic.

Valid stack values: node24 (recommended), node22, node20, node18, node16, node14, node12, java25, java21, java17, java11, java8, python_3_13, python_3_12, python_3_11, python_3_10

Environments

Catalyst has two environments:

1. Development (sandbox): CLI deploys go here. Free to use within limits. Used for testing.
2. Production: Requires billing setup. Serves live traffic. Deployed from the console, not CLI.

Application URL Format

The project domain is auto-generated when you first host a web client.

Dev-to-Prod promotion checklist

1. Verify in Development — all functions, AppSail, and frontend working correctly.
2. Set up billing — Catalyst Console → Settings → Billing.
3. Deploy to Production — Console → Deploy → select Production environment.
4. Update environment variables — Production uses separate env vars.
5. Reconfigure social login — OAuth redirect URLs must point to the Production domain.
6. Map custom domain — Console → Domain Mapping → add your production domain.
7. Test the full flow — auth, data, file uploads, email — all on the Production URL.
8. Monitor — enable APM and Application Alerts for Production.

Catalyst IDs Quick Reference

Table / Column IDs

// Access by name (case-sensitive — must match console exactly)
const table = catalystApp.datastore().table('Employees');

// Access by ID (from Console → Data Store → click table)
const table = catalystApp.datastore().table(1510000000110121);

Segment ID (Cache)

// Segment ID from Console → Cache → segment list
const segment = catalystApp.cache().segment(SEGMENT_ID);

Pool ID (Job Scheduling)

// Pool ID from Console → Job Scheduling → pool details
// ⚠️ There is NO .pool(POOL_ID) accessor in the Node SDK. Pools are read-only:
const pool = await catalystApp.jobScheduling().getJobpool(POOL_ID);
// Jobs/crons take the pool by name or id INSIDE their payload:
//   jobScheduling().job().submitJob({ ..., jobpool_id: POOL_ID })

Catalyst Organizations

Catalyst supports multiple organizations per account under the same email address.

Key concepts

• Org owner: Created the org. Can add collaborators (admins or project members), grant permissions per org or per project.
• Collaborator types: Admin (org-wide access) or Project Member (scoped to specific projects). Permissions are based on the assigned profile.
• Org ID: Auto-generated unique ID for each org. Part of the console URL: https://console.catalyst.zoho.com/baas/{OrgID}/index
• Default org: The org Catalyst assigns you to at signup. Can be changed to any other org you own.

Default organization behavior — critical for MCP and API usage

The default org affects everything:

• CLI login — always logs into the default org unless you switch explicitly.
• Every API call — executed against a project in the default org unless you pass the CATALYST-ORG: {org_id} header explicitly.
• MCP tools — CatalystbyZoho_* calls target the default org; always call List_All_Organizations first to confirm the correct org, then pass its ID in subsequent calls.

Cannot delete the default org. Set a different org as default before attempting to delete.

Accessing the multi-org organization

Console → profile icon (top-left) → Organizations dropdown → Manage Organizations

The organization view shows each org's unique ID and console URL.

Switching organizations via CLI

catalyst whoami            # shows current logged-in user
catalyst switch:org        # interactive org selector (arrow-key menu)

IaC Export / Import

Catalyst supports project export and import (Infrastructure as Code) for migrating between data centers, duplicating projects, or sharing project templates.

What is exported

• ✅ Component configurations (Data Store schema, Cache segments, Circuits, Security Rules, API Gateway routes, email templates, user profiles, etc.)
• ✅ Function and client code
• ❌ Data is NOT exported — no DataStore rows, no file contents, no user list records

How to export

Console → Settings → General → Export Project → downloads a ZIP file in Catalyst IaC format.

Also available via CLI:

catalyst project:export           # export to local directory
catalyst project:export --zip     # generate import-ready ZIP

How to import

Console → index page → Import Project → upload the ZIP → new project is created.

Also available via CLI:

catalyst project:import --file ./my-project.zip

Common use cases

Common Errors