> ## Documentation Index
> Fetch the complete documentation index at: https://keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow forms

> Publish a public form that starts a workflow run from a shareable link.

A workflow form is a public web page that collects a workflow's inputs and starts a run when someone submits it. Use one when you want humans outside your team (or without CLI/API access) to kick off a deployed workflow from a link.

Forms are a platform feature: they are published against a deployed workflow, not defined in project code. Field shape comes from the workflow's `input` schema. Presentation (labels, help text, controls) is configured when you publish.

## When to use a form

| Surface       | Best for                                                         |
| ------------- | ---------------------------------------------------------------- |
| **Form**      | A shareable link for people to fill in and submit                |
| **Triggers**  | Automated starts from webhooks, schedules, polls, and app events |
| **CLI / API** | You or your services starting runs with a known payload          |

Forms appear on the workflow canvas as a Form trigger once published. Submissions create normal [workflow runs](/docs/learn/logs/workflow-runs) you can inspect like any other surface.

## Requirements

* The workflow must be **deployed** and accept inputs (`input` schema with at least one field).
* Supported field types are scalars (`string`, `number`, `boolean`, `enum`) and arrays of scalars. **File**, **object**, and nested array fields are not supported yet.
* You need permission to manage the project (publish / unpublish / rotate).

## Publish from the dashboard

1. Open the workflow in the web app.
2. Use **Share → Publish a form**.
3. Optionally set a title, description, and per-field presentation (label, help text, placeholder, control).
4. Copy the public URL and share it.

You can customize presentation later from the same Share menu, unpublish to stop accepting submissions, or rotate the link to invalidate the old URL.

## Manage forms from the CLI

Forms are org/project-scoped like other platform commands. Link a project (or pass `--project`) so workflow slugs resolve unambiguously.

```bash theme={null}
keystroke workflows forms list
keystroke workflows forms publish request-review
keystroke workflows forms publish request-review \
  --title "Request a review" \
  --field-config '{"message":{"label":"What needs review?","control":"textarea"}}'
keystroke workflows forms url request-review
keystroke workflows forms get request-review
keystroke workflows forms unpublish request-review
keystroke workflows forms rotate request-review
```

| Command                            | Description                                                                                |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
| `workflows forms list`             | List forms in scope (`--admin` ignores linked project; explicit `--project` still narrows) |
| `workflows forms publish <slug>`   | Publish or update a form (`--title`, `--description`, `--config`, `--field-config`)        |
| `workflows forms get <slug>`       | Print the form JSON (or `null` if none)                                                    |
| `workflows forms url <slug>`       | Print the public URL (requires an enabled form)                                            |
| `workflows forms unpublish <slug>` | Stop accepting submissions                                                                 |
| `workflows forms rotate <slug>`    | Rotate the public link token                                                               |

`list` includes disabled (unpublished) forms; use the `enabled` field to see which still accept submissions. Full flag reference: [CLI — workflows](/docs/cli#workflows).

## Field presentation

`--field-config` (or the dashboard editor) is a JSON map of input field key → presentation options:

| Option        | Purpose                                        |
| ------------- | ---------------------------------------------- |
| `label`       | Override the field label                       |
| `helpText`    | Short helper under the field                   |
| `placeholder` | Placeholder text where the control supports it |
| `control`     | UI control for the field type                  |

Allowed controls by field type:

| Field type | Controls                                                            |
| ---------- | ------------------------------------------------------------------- |
| `string`   | `input`, `textarea`                                                 |
| `number`   | `input`, `stepper`, `slider` (slider needs `minimum` and `maximum`) |
| `boolean`  | `checkbox`, `switch`                                                |
| `enum`     | `select`, `radio`                                                   |

Unknown field keys or unsupported controls are rejected on publish. If the deployed schema later drops a field, stale config for that key is ignored on the public page so the form keeps working.

## Branding

Public forms show your organization and project name, plus optional org logos from workspace settings. Branding is not set on the form publish payload.

## Next steps

<CardGroup cols={2}>
  <Card title="Run workflows" href="/docs/learn/workflows/run-workflows">
    Triggers, CLI, API, and agent tools for starting runs.
  </Card>

  <Card title="Build workflows" href="/docs/learn/workflows/build-workflows">
    Define typed input schemas that drive the form fields.
  </Card>

  <Card title="CLI reference" href="/docs/cli#workflows">
    Full `workflows forms` command table.
  </Card>

  <Card title="Workflow runs" href="/docs/learn/logs/workflow-runs">
    Inspect submissions in run history.
  </Card>
</CardGroup>