From df865aa9f545ae02fde3cd7f9345859e262dc1e9 Mon Sep 17 00:00:00 2001
From: BR <51544548+Bradenream@users.noreply.github.com>
Date: Tue, 25 Aug 2026 20:33:57 -0400
Subject: [PATCH 1/3] docs: rewrite README for humans and coding agents
- Positioning header: what vf is and the surface it covers, replacing
the internal 'Realtime API' framing; license badge tracks the
Apache-2.0 decision
- Remove the pre-publish 'not ready for production' banner
- npm install (npx @voiceflow/cli) as the recommended install path
- Add an agent-executable quickstart: zero to a talking agent in four
commands, runnable end to end with only VF_TOKEN set, plus the traps
that break scripts (draft vs published, TOON default in agent mode,
--jq quoting, whoami being offline, vf docs for in-band lookup)
All edits are in hand-owned README space (outside Speakeasy's marker
pairs), so they persist across regenerations.
---
README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 52 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index 66ec620..13ede81 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,11 @@
-# vf
+# vf — the Voiceflow CLI
-Command-line interface for the *Realtime* API.
-
-[](https://www.speakeasy.com/?utm_source=github-com/voiceflow/cli&utm_campaign=cli)
-[](https://opensource.org/licenses/MIT)
+Build, test, and operate AI agents on [Voiceflow](https://www.voiceflow.com), the AI agent platform for customer experience automation — from your terminal, your CI, or your coding agent.
+`vf` covers the full agent lifecycle: workspaces, projects, environments, playbooks, functions, knowledge base documents, conversations, tests, evaluations, transcripts, and analytics. Every read command speaks JSON (and [TOON](https://github.com/toon-format/spec)); every failure names its own fix.
-
-> [!IMPORTANT]
-> This CLI is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/voiceflow/engineering). Delete this section before > publishing to a package manager.
+[](https://www.speakeasy.com/?utm_source=github-com/voiceflow/cli&utm_campaign=cli)
+[](https://opensource.org/licenses/Apache-2.0)
## Summary
@@ -38,6 +35,18 @@ Realtime: Realtime gateway API service
## CLI Installation
+### npm (recommended)
+
+```bash
+# Run without installing
+npx @voiceflow/cli --help
+
+# Or install globally (provides both `vf` and `voiceflow`)
+npm install -g @voiceflow/cli
+```
+
+Installs a prebuilt binary for your platform (macOS, Linux, Windows — arm64 and x64) with no postinstall scripts and no compilation.
+
### Quick Install (Linux/macOS)
```bash
@@ -63,6 +72,41 @@ go install github.com/voiceflow/cli/cmd/vf@latest
Download pre-built binaries for your platform from the [releases page](https://github.com/voiceflow/cli/releases).
+## Quickstart: zero to a talking agent
+
+Runnable end to end with nothing but an access token — by a person or by a coding agent. Create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
+
+```bash
+export VF_TOKEN=vfp_... # every command also accepts --token
+
+# 1. Pick a workspace (also proves the token works)
+WORKSPACE_ID=$(vf workspace list --output-format json | jq -r '.workspaces[0].id')
+
+# 2. Create an agent project
+PROJECT_ID=$(vf project create --name "My Agent" --type webchat \
+ --workspace-id "$WORKSPACE_ID" --output-format json | jq -r '.project.id')
+
+# 3. Start a conversation (fresh projects have one environment, alias "main")
+vf conversation send --user-id quickstart-user --project-id "$PROJECT_ID" \
+ --environment-alias main --version-param draft \
+ --action '{"type":"launch"}' --output-format json
+
+# 4. Say something — same user-id continues the same conversation
+vf conversation send --user-id quickstart-user --project-id "$PROJECT_ID" \
+ --environment-alias main --version-param draft \
+ --action '{"type":"text","payload":"What can you help me with?"}' --output-format json
+```
+
+The agent's replies arrive as `text` traces in the response. From here: edit the agent's instructions (`vf agent update`), add knowledge (`vf document create-url`), run tests (`vf test run create`), and publish (`vf environment publish`).
+
+Worth knowing before you script against the CLI:
+
+- **Use `--version-param draft`** — a fresh project has no published release yet.
+- **Pass `--output-format json` explicitly when piping.** Inside AI coding agents (`CLAUDE_CODE`, `CURSOR_AGENT`, …) the default output is TOON, not JSON.
+- **Capture values with `--output-format json | jq -r`** — the built-in `--jq` flag emits JSON, so strings keep their quotes.
+- **`vf whoami` is offline** — it shows which credential source is configured but does not validate the token. `vf workspace list` is the real check.
+- **Look things up in-band**: `vf docs search "publish an environment"` and `vf docs get ` bring the documentation to the terminal — no browser, no auth.
+
## Shell Completion
From 7e59ff591488fa0eaca46b2990fef50f986315c0 Mon Sep 17 00:00:00 2001
From: BR <51544548+Bradenream@users.noreply.github.com>
Date: Tue, 25 Aug 2026 22:41:37 -0400
Subject: [PATCH 2/3] fix: address adversarial-review findings on the README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Restore the '# vf' H1: retitling it broke the generated table of
contents' first anchor (#vf), which the TOC block still points at.
The descriptive positioning moves to the line below, where it reads
better anyway.
- Match PR #4's license-badge href exactly (opensource.org/license/...,
the canonical 200; /licenses/ 301-redirects) so the two PRs cannot
disagree about the final text.
- Drop '(recommended)' from the npm install heading — it is not a
superlative worth making while the package is not yet published; the
section is honest about what it does either way.
---
README.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index 13ede81..d0f4ed2 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
-# vf — the Voiceflow CLI
+# vf
-Build, test, and operate AI agents on [Voiceflow](https://www.voiceflow.com), the AI agent platform for customer experience automation — from your terminal, your CI, or your coding agent.
+The Voiceflow CLI. Build, test, and operate AI agents on [Voiceflow](https://www.voiceflow.com), the AI agent platform for customer experience automation — from your terminal, your CI, or your coding agent.
`vf` covers the full agent lifecycle: workspaces, projects, environments, playbooks, functions, knowledge base documents, conversations, tests, evaluations, transcripts, and analytics. Every read command speaks JSON (and [TOON](https://github.com/toon-format/spec)); every failure names its own fix.
[](https://www.speakeasy.com/?utm_source=github-com/voiceflow/cli&utm_campaign=cli)
-[](https://opensource.org/licenses/Apache-2.0)
+[](https://opensource.org/license/Apache-2.0)
## Summary
@@ -35,7 +35,7 @@ Realtime: Realtime gateway API service
## CLI Installation
-### npm (recommended)
+### npm
```bash
# Run without installing
From fa62ca3c59748c3da11c7f67ef22b4672f8e903b Mon Sep 17 00:00:00 2001
From: BR <51544548+Bradenream@users.noreply.github.com>
Date: Wed, 26 Aug 2026 00:29:40 -0400
Subject: [PATCH 3/3] docs: make the install command unattended-safe and name
the jq dependency
Copilot review, both real gaps for the audience this README targets:
- 'npx @voiceflow/cli' prompts 'Ok to proceed?' when a TTY is present and
the package is not already cached, which stalls exactly the unattended
agent run the quickstart exists to serve. Use 'npx -y'.
- The quickstart claimed it needed nothing but an access token while its
commands pipe through jq to capture IDs. Name the dependency.
---
README.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index d0f4ed2..c278746 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ Realtime: Realtime gateway API service
```bash
# Run without installing
-npx @voiceflow/cli --help
+npx -y @voiceflow/cli --help
# Or install globally (provides both `vf` and `voiceflow`)
npm install -g @voiceflow/cli
@@ -74,7 +74,7 @@ Download pre-built binaries for your platform from the [releases page](https://g
## Quickstart: zero to a talking agent
-Runnable end to end with nothing but an access token — by a person or by a coding agent. Create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
+Runnable end to end by a person or by a coding agent. You need an access token and [`jq`](https://jqlang.org) (used only to pull IDs out of the JSON responses). Create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
```bash
export VF_TOKEN=vfp_... # every command also accepts --token