Corezoid Variable Manager

Corezoid Variable Manager

How to call these tools

Every operation in this skill is an action of the single cz-variables MCP tool — the individual names below are action strings, not tools of their own:

Copy code
cz-variables {"action": "list-variables"}

Arguments always go inside args; the shorthand used in the examples below — create-variable(name="payment-api-url", …) — means exactly that call. When unsure about an action's arguments, call cz-variables {"action": "<action>", "help": true} — it returns the full schema and runs nothing.

What variables are

Environment variables store constants (URLs, tokens, API keys, IDs, configuration values) that must not be hardcoded in process logic. The reference syntax {{env_var[@name]}} is resolved at runtime — changing a variable value takes effect immediately without redeploying any process.

Variables are stage-scoped: shared across all processes within a stage.

Variable types

By data type

By visibility

⚠️ Secret variables are designed for tokens, passwords, and API keys. They are never returned in plain text by the API after creation — only an MD5/SHA256 fingerprint is available. Use visible for non-sensitive configuration.

Actions of cz-variables

Note: creating secret or json variables is not yet exposed as an action — use the direct API calls documented below for creation; manage them afterwards with the actions above.

Double-confirmation etiquette (modify / delete)

modify-variable and delete-variable are consequential: a deleted variable is gone FOREVER (env vars have NO recycle bin), a renamed one breaks every {{env_var[@old-name]}} reference, and a changed value takes effect immediately in running processes. The actions enforce a two-step gate, and you must drive it honestly:

1. Call the action WITHOUT apply — you get a dry-run: a current → new diff (modify) or a red 🔴 PERMANENT DELETION block (delete), including a local reference scan.
2. Show that dry-run output to the user verbatim — do not summarize away the warnings, especially the red block and the list of files that still reference the variable.
3. Ask the user explicitly whether to proceed, and wait for their clear agreement in the conversation.
4. Only then re-run with apply=true and the exact confirm="<short_name>#<obj_id>" from the dry-run output. Never fabricate the confirm string without steps 1–3, and never treat an earlier, unrelated "yes" as agreement for this action.

Server facts the tools rely on (verified live): modify is PARTIAL — omitted fields keep their value, so modifying a secret's title does not require (or touch) its value; env_var_type (visible/secret) can NOT be changed after creation — the server silently ignores such attempts; delete requires project_id + stage_id and is irreversible.

Using variables in process JSON

Once a variable exists, reference it with {{env_var[@short-name]}} anywhere a value is expected.

API Call node — URL field

jsonCopy code
{
  "type": "api",
  "url": "{{env_var[@payment-api-url]}}/charge",
  "method": "POST",
  "extra_headers": {},
  "max_threads": 5,
  "err_node_id": "<error_node_id>"
}

API Call node — header field

jsonCopy code
{
  "type": "api",
  "url": "{{env_var[@payment-api-url]}}/charge",
  "method": "POST",
  "extra_headers": {},
  "max_threads": 5,
  "extra": { "Authorization": "Bearer {{env_var[@payment-api-token]}}" },
  "extra_type": { "Authorization": "string" },
  "err_node_id": "<error_node_id>"
}

Set Parameters node

jsonCopy code
{
  "type": "set_param",
  "extra": {
    "baseUrl": "{{env_var[@service-url]}}",
    "token":   "{{env_var[@service-token]}}"
  },
  "extra_type": {
    "baseUrl": "string",
    "token":   "string"
  },
  "err_node_id": "<error_node_id>"
}

Call a Process node — passing variable as parameter

jsonCopy code
{
  "type": "api_rpc",
  "conv_id": "@target-process",
  "extra": { "endpoint": "{{env_var[@service-endpoint]}}" },
  "extra_type": { "endpoint": "string" },
  "err_node_id": "<error_node_id>"
}

Condition node (go_if_const)

Variable references work in condition expressions as both the left-hand value and the comparison value:

jsonCopy code
{
  "type": "go_if_const",
  "conditions": [
    {
      "fun": "equal",
      "arg": "{{env_var[@feature-flag]}}",
      "val": "enabled"
    }
  ],
  "to_node_id": "<next_node_id>"
}

Code node — variables must be pre-loaded via set_param

Variables are not directly accessible inside api_code JavaScript. First assign them to task fields using a set_param node upstream, then read via data.* in code:

javascriptCopy code
// In set_param upstream: "apiUrl": "{{env_var[@my-api-url]}}"
var url = data.apiUrl + "/endpoint";

Naming rules

• Only lowercase letters [a-z], digits [0-9], and hyphens -
• Name and description must be at least 3 characters
• Must be unique within the stage
• Good: stripe-secret-key, payment-api-url, db-host-prod
• Bad: URL, TOKEN, x, My_Var

Local cache files

Two files store variable information locally. Check both before creating a new variable:

If neither file exists, run pull-folder or call the list API (see below) to get the current state.

Workflow: Create a visible raw variable (MCP tool)

Step 1 — Check if variable already exists

Read _ENV_VARS_.json (or .processes/variables.json) and search for the short_name. If found, reuse it — do not create a duplicate.

Step 2 — Create the variable

Call cz-variables with action: "create-variable" and these args:

• name: the short_name (kebab-case, e.g. stripe-api-key)
• description: human-readable label (min 3 chars), used as title in the API
• value: the actual value

Copy code
cz-variables {"action": "create-variable", "args": {
  "name": "payment-api-url",
  "description": "Payment Service Base URL",
  "value": "https://api.payments.example.com"
}}

The action creates the variable in Corezoid and appends it to .processes/variables.json.

Step 3 — Reference in process JSON

Use {{env_var[@payment-api-url]}} wherever this value is needed.

Workflow: Create a secret variable (direct API)

Use when storing tokens, passwords, API keys — values that must be masked in the UI.

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type":         "create",
    "obj":          "env_var",
    "obj_type":     0,
    "status":       "active",
    "data_type":    "raw",
    "env_var_type": "secret",
    "title":        "Stripe Secret Key",
    "short_name":   "stripe-secret-key",
    "description":  "",
    "value":        "sk_live_...",
    "company_id":   "<WORKSPACE_ID>",
    "project_id":   <PROJECT_ID>,
    "stage_id":     <STAGE_ID>,
    "scopes":       [{"type": "api_call", "fields": "*"}]
  }]
}

Response: { "obj_id": 2192, "proc": "ok", "fingerprints": [...] }

The value is never returned after creation. Store it securely before calling this API.

Workflow: Create a JSON variable (direct API)

Use when a variable holds a structured config object or array.

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type":         "create",
    "obj":          "env_var",
    "obj_type":     0,
    "status":       "active",
    "data_type":    "json",
    "env_var_type": "visible",
    "title":        "Service Config",
    "short_name":   "service-config",
    "description":  "",
    "value":        "{\"host\":\"db.example.com\",\"port\":5432,\"name\":\"prod\"}",
    "company_id":   "<WORKSPACE_ID>",
    "project_id":   <PROJECT_ID>,
    "stage_id":     <STAGE_ID>,
    "scopes":       [{"type": "*", "fields": "*"}]
  }]
}

The value field must be a JSON string (the JSON content encoded as a string). A secret JSON variable uses "env_var_type": "secret" and "scopes": [{"type": "api_call", "fields": "*"}].

Workflow: List variables (direct API)

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type":       "list",
    "obj":        "env_var",
    "sort":       "date",
    "order":      "asc",
    "id":         "<WORKSPACE_ID>",
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id":   <STAGE_ID>
  }]
}

Response fields per variable:

Workflow: Modify a variable (direct API)

Modify updates all mutable fields in one call. Always send the full payload — partial updates are not supported.

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type":         "modify",
    "obj":          "env_var",
    "obj_id":       <VAR_OBJ_ID>,
    "data_type":    "raw",
    "env_var_type": "visible",
    "title":        "Updated Display Title",
    "short_name":   "new-short-name",
    "description":  "",
    "value":        "new-value",
    "company_id":   "<WORKSPACE_ID>",
    "project_id":   <PROJECT_ID>,
    "stage_id":     <STAGE_ID>,
    "scopes":       [{"type": "*", "fields": "*"}]
  }]
}

⚠️ Changing short_name invalidates all {{env_var[@old-name]}} references across every process in the stage. After renaming, grep all .conv.json files for the old name and update them, then push-process each affected file.

Workflow: Delete a variable (direct API)

⚠️ Before deleting, verify no process references {{env_var[@short-name]}}. push-process validates env_var references and will fail if the variable is missing.

bashCopy code
# Check which processes reference this variable
grep -r "env_var\[@variable-name\]" . --include="*.conv.json"

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type":       "delete",
    "obj":        "env_var",
    "obj_id":     <VAR_OBJ_ID>,
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id":   <STAGE_ID>
  }]
}

Resolving environment values

When calling the create-variable / modify-variable / delete-variable / list-variables actions you do not need to look up stage_id or project_id — MCP resolves both from the <id>_<name>.stage.json marker at the workspace root.

For direct /api/2/json calls (the raw workflows below) you need the values explicitly:

If the marker file is missing, run the corezoid-init skill.

Runtime behaviour

• Variables are resolved before the node executes — the {{env_var[@name]}} token is replaced with the live value at the moment the task reaches that node
• Updating a variable value takes effect immediately — no process redeploy needed
• push-process validates all {{env_var[@name]}} references: if the variable does not exist in the stage, deployment fails with an error

Common pitfalls

Reference Documents