Can I use Tally as a CLI?

Yes. KosmoKrator exposes a Tally CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Tally through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Tally tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Tally credentials stored?

Tally credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Tally MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Tally Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Tally KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.tally.*. Use lua_read_doc("integrations.tally") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Tally workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.tally.api_delete({path = "example_path", payload = "example_payload"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("tally"))' --json
kosmo integrations:lua --eval 'print(docs.read("tally.api_delete"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local tally = app.integrations.tally
local result = tally.api_delete({path = "example_path", payload = "example_payload"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.tally, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.tally.default.* or app.integrations.tally.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Tally, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Tally Lua API Reference

Namespace: app.integrations.tally

Use Tally for form discovery, submission review, workspace administration, organization invites, and webhook delivery management. Results are Tally JSON responses with minimal reshaping; tool parameters are snake_case even when Tally’s API uses camelCase fields.

Common Reads

local user = app.integrations.tally.get_current_user({})

local forms = app.integrations.tally.list_forms({
  limit = 50,
  workspace_ids = { "ws_example" }
})

local form = app.integrations.tally.get_form({ form_id = "form_example" })
local questions = app.integrations.tally.list_questions({ form_id = "form_example" })
local blocks = app.integrations.tally.list_blocks({ form_id = "form_example" })

list_forms accepts page, limit, and workspace_ids. Tally returns paginated objects with fields such as items, page, limit, total, and hasMore.

Forms And Structure

local created = app.integrations.tally.create_form({
  workspace_id = "ws_example",
  status = "draft",
  blocks = {
    { type = "TITLE", payload = { text = "Contact us" } }
  }
})

app.integrations.tally.update_form({
  form_id = created.id,
  name = "Contact form",
  status = "published"
})

app.integrations.tally.update_question({
  form_id = created.id,
  question_id = "question_example",
  title = "What should we know?"
})

app.integrations.tally.update_blocks({
  form_id = created.id,
  blocks = {
    { id = "block_example", type = "TITLE", payload = { text = "Updated" } }
  }
})

Creating and updating forms accepts Tally block and settings payloads. Fetch an existing form or blocks first when making structural edits so the agent preserves fields that should remain unchanged.

Submissions

local submissions = app.integrations.tally.list_submissions({
  form_id = "form_example",
  filter = "completed",
  start_date = "2026-01-01T00:00:00Z",
  limit = 100
})

local submission = app.integrations.tally.get_submission({
  form_id = "form_example",
  submission_id = "submission_example"
})

Submission access is form-scoped in the current Tally API. Always pass both form_id and submission_id for single-submission reads or deletes. list_submissions accepts page, limit, filter (all, completed, partial), start_date, end_date, and after_id.

Workspaces And Organizations

local workspaces = app.integrations.tally.list_workspaces({ page = 1 })
local workspace = app.integrations.tally.get_workspace({ workspace_id = "ws_example" })

app.integrations.tally.create_organization_invite({
  organization_id = "org_example",
  workspace_ids = { "ws_example" },
  emails = "person@example.test"
})

local invites = app.integrations.tally.list_organization_invites({
  organization_id = "org_example"
})

Workspace tools can create, get, update, and delete workspaces. Organization tools can list users, remove users, list invites, create invites, and cancel pending invites.

Webhooks

local hook = app.integrations.tally.create_webhook({
  form_id = "form_example",
  url = "https://example.test/tally/webhook",
  event_types = { "FORM_RESPONSE" },
  signing_secret = "dummy-secret"
})

local events = app.integrations.tally.list_webhook_events({
  webhook_id = hook.id,
  page = 1
})

app.integrations.tally.retry_webhook_event({
  webhook_id = hook.id,
  event_id = "event_example"
})

Webhook tools manage subscriptions and delivery events. http_headers should be an array of objects with name and value keys when custom delivery headers are needed.

Generic API Tools

local raw = app.integrations.tally.api_get({
  path = "/forms",
  params = { limit = 10 }
})

Use api_get, api_post, api_patch, and api_delete only for documented Tally endpoints that are not yet wrapped by a named helper. Prefer named tools because they validate required IDs and map snake_case parameters for you.

Multi-Account Usage

app.integrations.tally.list_forms({})
app.integrations.tally.default.list_forms({})
app.integrations.tally.work.list_forms({})

All account namespaces expose the same tools; only stored credentials differ.

Raw agent markdown

# Tally Lua API Reference

Namespace: `app.integrations.tally`

Use Tally for form discovery, submission review, workspace administration, organization invites, and webhook delivery management. Results are Tally JSON responses with minimal reshaping; tool parameters are `snake_case` even when Tally's API uses camelCase fields.

## Common Reads

```lua
local user = app.integrations.tally.get_current_user({})

local forms = app.integrations.tally.list_forms({
  limit = 50,
  workspace_ids = { "ws_example" }
})

local form = app.integrations.tally.get_form({ form_id = "form_example" })
local questions = app.integrations.tally.list_questions({ form_id = "form_example" })
local blocks = app.integrations.tally.list_blocks({ form_id = "form_example" })
```

`list_forms` accepts `page`, `limit`, and `workspace_ids`. Tally returns paginated objects with fields such as `items`, `page`, `limit`, `total`, and `hasMore`.

## Forms And Structure

```lua
local created = app.integrations.tally.create_form({
  workspace_id = "ws_example",
  status = "draft",
  blocks = {
    { type = "TITLE", payload = { text = "Contact us" } }
  }
})

app.integrations.tally.update_form({
  form_id = created.id,
  name = "Contact form",
  status = "published"
})

app.integrations.tally.update_question({
  form_id = created.id,
  question_id = "question_example",
  title = "What should we know?"
})

app.integrations.tally.update_blocks({
  form_id = created.id,
  blocks = {
    { id = "block_example", type = "TITLE", payload = { text = "Updated" } }
  }
})
```

Creating and updating forms accepts Tally block and settings payloads. Fetch an existing form or blocks first when making structural edits so the agent preserves fields that should remain unchanged.

## Submissions

```lua
local submissions = app.integrations.tally.list_submissions({
  form_id = "form_example",
  filter = "completed",
  start_date = "2026-01-01T00:00:00Z",
  limit = 100
})

local submission = app.integrations.tally.get_submission({
  form_id = "form_example",
  submission_id = "submission_example"
})
```

Submission access is form-scoped in the current Tally API. Always pass both `form_id` and `submission_id` for single-submission reads or deletes. `list_submissions` accepts `page`, `limit`, `filter` (`all`, `completed`, `partial`), `start_date`, `end_date`, and `after_id`.

## Workspaces And Organizations

```lua
local workspaces = app.integrations.tally.list_workspaces({ page = 1 })
local workspace = app.integrations.tally.get_workspace({ workspace_id = "ws_example" })

app.integrations.tally.create_organization_invite({
  organization_id = "org_example",
  workspace_ids = { "ws_example" },
  emails = "person@example.test"
})

local invites = app.integrations.tally.list_organization_invites({
  organization_id = "org_example"
})
```

Workspace tools can create, get, update, and delete workspaces. Organization tools can list users, remove users, list invites, create invites, and cancel pending invites.

## Webhooks

```lua
local hook = app.integrations.tally.create_webhook({
  form_id = "form_example",
  url = "https://example.test/tally/webhook",
  event_types = { "FORM_RESPONSE" },
  signing_secret = "dummy-secret"
})

local events = app.integrations.tally.list_webhook_events({
  webhook_id = hook.id,
  page = 1
})

app.integrations.tally.retry_webhook_event({
  webhook_id = hook.id,
  event_id = "event_example"
})
```

Webhook tools manage subscriptions and delivery events. `http_headers` should be an array of objects with `name` and `value` keys when custom delivery headers are needed.

## Generic API Tools

```lua
local raw = app.integrations.tally.api_get({
  path = "/forms",
  params = { limit = 10 }
})
```

Use `api_get`, `api_post`, `api_patch`, and `api_delete` only for documented Tally endpoints that are not yet wrapped by a named helper. Prefer named tools because they validate required IDs and map snake_case parameters for you.

## Multi-Account Usage

```lua
app.integrations.tally.list_forms({})
app.integrations.tally.default.list_forms({})
app.integrations.tally.work.list_forms({})
```

All account namespaces expose the same tools; only stored credentials differ.

Metadata-derived Lua example

local result = app.integrations.tally.api_delete({path = "example_path", payload = "example_payload"})
print(result)

Functions

api_delete Read

Call a documented Tally DELETE API path. Prefer named Tally tools when one exists.

Lua path: app.integrations.tally.api_delete
Full name: tally.tally_api_delete

Parameter	Type	Required	Description
`path`	string	yes	API path, for example /forms/{formId}.
`payload`	object	no	Optional JSON request body.

api_get Read

Call a documented Tally GET API path. Prefer named Tally tools when one exists.

Lua path: app.integrations.tally.api_get
Full name: tally.tally_api_get

Parameter	Type	Required	Description
`path`	string	yes	API path, for example /forms.
`params`	object	no	Query parameters.

api_patch Read

Call a documented Tally PATCH API path. Prefer named Tally tools when one exists.

Lua path: app.integrations.tally.api_patch
Full name: tally.tally_api_patch

Parameter	Type	Required	Description
`path`	string	yes	API path, for example /forms/{formId}.
`payload`	object	no	JSON request body.

api_post Read

Call a documented Tally POST API path. Prefer named Tally tools when one exists.

Lua path: app.integrations.tally.api_post
Full name: tally.tally_api_post

Parameter	Type	Required	Description
`path`	string	yes	API path, for example /webhooks.
`payload`	object	no	JSON request body.

cancel_organization_invite Write

Cancel a pending Tally organization invite.

Lua path: app.integrations.tally.cancel_organization_invite
Full name: tally.tally_cancel_organization_invite

Parameter	Type	Required	Description
`organization_id`	string	yes	The Tally organization ID.
`invite_id`	string	yes	The Tally invite ID.

create_form Write

Create a new Tally form using blocks, settings, a workspace, a template, and an optional initial status.

Lua path: app.integrations.tally.create_form
Full name: tally.tally_create_form

Parameter	Type	Required	Description
`workspace_id`	string	no	Workspace ID to create the form in.
`template_id`	string	no	Template ID to base the form on.
`status`	string	no	Initial form status.
`blocks`	array	no	Tally block payloads.
`settings`	object	no	Tally form settings.

create_organization_invite Write

Invite users to one or more Tally workspaces inside an organization.

Lua path: app.integrations.tally.create_organization_invite
Full name: tally.tally_create_organization_invite

Parameter	Type	Required	Description
`organization_id`	string	yes	The Tally organization ID.
`workspace_ids`	array	yes	Workspace IDs to invite users to.
`emails`	string	yes	Comma- or semicolon-separated email addresses.

create_webhook Write

Create a Tally webhook subscription for a form.

Lua path: app.integrations.tally.create_webhook
Full name: tally.tally_create_webhook

Parameter	Type	Required	Description
`form_id`	string	yes	Form ID to subscribe to.
`url`	string	yes	Webhook target URL.
`event_types`	array	yes	Event types to receive.
`signing_secret`	string	no	Optional webhook signing secret.
`http_headers`	array	no	Optional custom headers.
`external_subscriber`	string	no	Optional external subscriber identifier.

create_workspace Write

Create a Tally workspace by name.

Lua path: app.integrations.tally.create_workspace
Full name: tally.tally_create_workspace

Parameter	Type	Required	Description
`name`	string	yes	Workspace name.

delete_form Write

Delete a Tally form by ID.

Lua path: app.integrations.tally.delete_form
Full name: tally.tally_delete_form

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.

delete_submission Write

Delete a Tally submission by form ID and submission ID.

Lua path: app.integrations.tally.delete_submission
Full name: tally.tally_delete_submission

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.
`submission_id`	string	yes	The Tally submission ID.

delete_webhook Write

Delete a Tally webhook subscription by ID.

Lua path: app.integrations.tally.delete_webhook
Full name: tally.tally_delete_webhook

Parameter	Type	Required	Description
`webhook_id`	string	yes	The Tally webhook ID.

delete_workspace Write

Delete a Tally workspace by ID.

Lua path: app.integrations.tally.delete_workspace
Full name: tally.tally_delete_workspace

Parameter	Type	Required	Description
`workspace_id`	string	yes	The Tally workspace ID.

get_current_user Read

Get the authenticated user's profile information, including name, email, and account details.

Lua path: app.integrations.tally.get_current_user
Full name: tally.tally_get_current_user

Parameter	Type	Required	Description
No parameters.

get_form Read

Get full details of a specific Tally form by its ID, including form structure, fields, and settings.

Lua path: app.integrations.tally.get_form
Full name: tally.tally_get_form

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID (e.g., "mVlBRN").

get_submission Read

Get full details of a specific form submission by its ID, including all field responses and metadata.

Lua path: app.integrations.tally.get_submission
Full name: tally.tally_get_submission

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID that owns the submission.
`submission_id`	string	yes	The Tally submission ID.

get_workspace Read

Get a Tally workspace by ID.

Lua path: app.integrations.tally.get_workspace
Full name: tally.tally_get_workspace

Parameter	Type	Required	Description
`workspace_id`	string	yes	The Tally workspace ID.

list_blocks Read

List blocks for a Tally form.

Lua path: app.integrations.tally.list_blocks
Full name: tally.tally_list_blocks

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.

list_forms Read

List all Tally forms accessible to the authenticated user. Returns form IDs, titles, status, and submission counts. Supports pagination.

Lua path: app.integrations.tally.list_forms
Full name: tally.tally_list_forms

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`limit`	integer	no	Number of forms per page (default: 50, max: 500).
`workspace_ids`	array	no	Optional workspace IDs to filter forms by.

list_organization_invites Read

List pending invites for a Tally organization.

Lua path: app.integrations.tally.list_organization_invites
Full name: tally.tally_list_organization_invites

Parameter	Type	Required	Description
`organization_id`	string	yes	The Tally organization ID.

list_organization_users Read

List users in a Tally organization.

Lua path: app.integrations.tally.list_organization_users
Full name: tally.tally_list_organization_users

Parameter	Type	Required	Description
`organization_id`	string	yes	The Tally organization ID.

list_questions Read

List questions for a Tally form.

Lua path: app.integrations.tally.list_questions
Full name: tally.tally_list_questions

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.

list_submissions Read

List all submissions for a specific Tally form. Returns respondent answers, submission dates, and metadata. Supports pagination.

Lua path: app.integrations.tally.list_submissions
Full name: tally.tally_list_submissions

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID to retrieve submissions for (e.g., "mVlBRN").
`page`	integer	no	Page number for pagination (default: 1).
`limit`	integer	no	Number of submissions per page (default: 50, max: 500).
`filter`	string	no	Submission status filter.
`start_date`	string	no	Return submissions submitted on or after this ISO 8601 timestamp.
`end_date`	string	no	Return submissions submitted on or before this ISO 8601 timestamp.
`after_id`	string	no	Return submissions after this submission ID.

list_webhook_events Read

List delivery events for a Tally webhook.

Lua path: app.integrations.tally.list_webhook_events
Full name: tally.tally_list_webhook_events

Parameter	Type	Required	Description
`webhook_id`	string	yes	The Tally webhook ID.
`page`	integer	no	Page number.

list_webhooks Read

List Tally webhook subscriptions with pagination.

Lua path: app.integrations.tally.list_webhooks
Full name: tally.tally_list_webhooks

Parameter	Type	Required	Description
`page`	integer	no	Page number.
`limit`	integer	no	Number of webhooks per page, max 100.

list_workspaces Read

List all workspaces accessible to the authenticated Tally user. Returns workspace names, IDs, and member info.

Lua path: app.integrations.tally.list_workspaces
Full name: tally.tally_list_workspaces

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination.

remove_organization_user Write

Remove a user from a Tally organization.

Lua path: app.integrations.tally.remove_organization_user
Full name: tally.tally_remove_organization_user

Parameter	Type	Required	Description
`organization_id`	string	yes	The Tally organization ID.
`user_id`	string	yes	The Tally user ID.

retry_webhook_event Read

Retry a Tally webhook delivery event.

Lua path: app.integrations.tally.retry_webhook_event
Full name: tally.tally_retry_webhook_event

Parameter	Type	Required	Description
`webhook_id`	string	yes	The Tally webhook ID.
`event_id`	string	yes	The Tally webhook event ID.

update_blocks Write

Replace the block tree for a Tally form.

Lua path: app.integrations.tally.update_blocks
Full name: tally.tally_update_blocks

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.
`blocks`	array	yes	Full replacement block array.

update_form Write

Update a Tally form name, status, blocks, or settings.

Lua path: app.integrations.tally.update_form
Full name: tally.tally_update_form

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.
`name`	string	no	New form name.
`status`	string	no	New form status.
`blocks`	array	no	Updated Tally blocks.
`settings`	object	no	Updated Tally settings.

update_question Write

Update a Tally question title by form and question ID.

Lua path: app.integrations.tally.update_question
Full name: tally.tally_update_question

Parameter	Type	Required	Description
`form_id`	string	yes	The Tally form ID.
`question_id`	string	yes	The Tally question ID.
`title`	string	yes	New question title.

update_webhook Write

Update a Tally webhook target, event types, headers, signing secret, or enabled state.

Lua path: app.integrations.tally.update_webhook
Full name: tally.tally_update_webhook

Parameter	Type	Required	Description
`webhook_id`	string	yes	The Tally webhook ID.
`form_id`	string	no	Form ID the webhook belongs to.
`url`	string	no	Webhook target URL.
`event_types`	array	no	Event types to receive.
`is_enabled`	boolean	no	Whether the webhook is enabled.
`signing_secret`	string	no	Optional webhook signing secret.
`http_headers`	array	no	Optional custom headers.

update_workspace Write

Rename a Tally workspace.

Lua path: app.integrations.tally.update_workspace
Full name: tally.tally_update_workspace

Parameter	Type	Required	Description
`workspace_id`	string	yes	The Tally workspace ID.
`name`	string	yes	New workspace name.