Imported from asksyllable/syllable-cli (.claude/skills/syllable-cli/SKILL.md). Install upstream with npx skills add asksyllable/syllable-cli --skill syllable-cli. Copyright stays with the author.

Syllable CLI

A Go CLI for managing the Syllable AI platform. Source and releases: https://github.com/asksyllable/syllable-cli

Docs synced to CLI v2.2.0 — bump this marker whenever these docs are updated for a new release.

v2.2.0 (minor) highlights — purely additive, no breaking changes: new sessions timeline <session-id> command returning one consolidated, time-ordered stream of transcript turns, tool calls, and latency events with offsets from session start; outbound batch create/update bodies accept call_rate and auto_call_rate (per-batch rate control, with auto_call_rate_baseline in responses); SipConfiguration gains call_info_placement; sessions expose override_timestamp; new Cartesia TTS provider with the sonic-3.5 voice model and 18 new voices across US/MX/ES/KR/CN/VN/TH.

v2.1.0 (minor) highlights — purely additive, no breaking changes: new bridge-phrases command (list/get/create/update/delete) for the named, reusable hold-phrase configs, attached to an agent via bridge_phrases_id; conversation-config bridges and bridges-update take optional --agent-id / --tool-name to scope the config (omit both for the org-level default); sessions list --include-test help text corrected — the flag keys off the session-level is_test flag, not channel targets.

v2.0.0 (major) highlights — the breaking changes still apply: destructive delete commands confirm interactively and need --yes when non-interactive; channels delete was removed (no such API op — use channels targets delete); data-sources create inline takes --text (the document-body field) in place of the old, non-functional --content. Also: --output is validated; unknown --fields columns warn; --dry-run lists any missing_required_fields; --debug redacts credentials.

Installation

Homebrew (recommended for macOS/Linux):

brew tap asksyllable/syllable-cli https://github.com/asksyllable/syllable-cli
brew install --cask syllable

Install script:

curl -fsSL https://github.com/asksyllable/syllable-cli/releases/latest/download/install.sh | sh

Setup — First Time and Any Config Changes

Any time the user needs to configure the CLI — whether it's the first time, adding a new org, adding a new environment, or updating an API key — run:

syllable setup

This opens a browser UI where the user can safely manage all orgs, API keys, and environments. Always use this command for config changes — never edit ~/.syllable/config.yaml directly or ask the user to paste API keys into the terminal.

Trigger syllable setup whenever the user says things like:

• "I need to add a new org"
• "Add a new environment"
• "Update my API key"
• "Set up credentials for [org]"
• "I'm getting auth errors" (may need a key update)
• First use — if ~/.syllable/config.yaml doesn't exist or has no orgs configured

Check if setup is needed:

test -f ~/.syllable/config.yaml && echo "configured" || echo "not configured"

IMPORTANT — Never read or display config files. The config at ~/.syllable/config.yaml contains API keys. Never cat, read, head, or otherwise output its contents. Use syllable setup for any config changes and the test -f check above to verify it exists.

Org & Environment Confirmation

Before executing any command that reads or modifies platform resources, always confirm the target org and environment with the user. Run syllable status first to see all configured orgs and environments:

syllable status

This shows each configured org, its environment(s), and whether an API key is present. Use it to:

• Resolve vague user references — e.g., "acme" → find the matching configured org name like acme-health or acme
• Discover org naming conventions — see the exact short names configured
• Confirm the target before executing — especially for create, update, or delete operations
• Verify environment — ensure you're targeting prod vs. staging vs. dev

Always tell the user which org and environment you're about to run against and get confirmation before proceeding, particularly for write operations.

Bridge Phrases — Confirm Which Config Surface First

Two commands write bridge phrases, with separate storage. Writing the wrong one appears to succeed and changes nothing the agent actually uses.

Before any bridge-phrase write, ask the user which of the two they mean. Do not guess, and do not default to one.

If the user doesn't know, ask them to check the Console: does the agent's config page let them set a bridge phrase config per agent?

• Yes → use bridge-phrases.
• No → use conversation-config bridges-update.

conversation-config is slated for deprecation; bridge-phrases is the forward-looking surface. Until that lands, both are live and the question above is the only reliable way to tell which one an org is on — the API answers a write to either with a 200 regardless.

Reads skip only the which-surface question — the org & environment confirmation above still applies to them. When diagnosing, reading both is often the fastest way to find where an org's phrases actually live:

syllable bridge-phrases list
syllable conversation-config bridges
syllable conversation-config bridges --agent-id <id>

Full field shapes and gotchas: references/commands.md § Bridge Phrases, references/gotchas.md § Bridge Phrases — two separate surfaces.

Quick Start

syllable --help

Select an org per command:

syllable --org acme agents list
syllable --org globex sessions list

If default_org is set in ~/.syllable/config.yaml, it's used when --org is omitted.

Global Flags

Common List Flags

All list commands support these flags:

For sessions, the valid --search-field values are the SessionProperties enum — syllable schema get SessionProperties lists them (agent_name, source, target, channel_manager_sid, prompt_name, is_outbound, …). String fields filter server-side; filter boolean fields (is_test, is_outbound) client-side with jq — see references/gotchas.md.

Default search field by resource:

Resources & Verbs (summary)

Every command takes the form syllable [--org X] [--env Y] <resource> <verb> [args].

Resources: agents, prompts, tools, services, channels (+ channels targets, channels twilio, channels available-targets), sessions, conversations, outbound batches, outbound campaigns, users, directory, insights workflows, insights folders, insights tool-configs, insights tool-definitions, custom-messages, language-groups (deprecated → use voice-groups), voice-groups, data-sources, roles, incidents, pronunciations, session-labels, session-debug, takeouts, events, permissions, bridge-phrases, conversation-config (slated for deprecation → prefer bridge-phrases), dashboards, organizations (current-org get/update + sip-ip-ranges; no create/delete), schema, status.

Standard verbs (most resources):

syllable <resource> list [--page N] [--limit N] [--search TEXT]
syllable <resource> get <id>
syllable <resource> create --file body.json     # or inline flags (see references/commands.md)
syllable <resource> update <id> --file body.json # PUT, full replacement — see warning below
syllable <resource> delete <id> --yes            # destructive — see note below

Destructive commands confirm first. delete prompts for a y/N confirmation. Running non-interactively (scripts, CI, an agent driving the CLI) you must pass --yes/-y or the command refuses with an error and does nothing. --dry-run previews the request without deleting. (users delete-account and the pronunciation-CSV commands keep their own --confirm flag.)

Resource-specific verbs worth knowing inline:

<id> for sessions is the numeric Syllable session ID (e.g., 824) — not the Twilio CA<hex> call SID. Any session_id-keyed call (sessions get/transcript/summary, GET /sessions/full-summary/{session_id}, sdk.sessions.getById) returns 400 on a CA… SID; that value is the session's channel_manager_sid. To resolve one from the other: sessions list --search-field channel_manager_sid --search "CA…" -o json. See references/sessions-and-debugging.md.

For exact flag syntax, table-column listings, get-fields, inline-create flag sets, and resource-specific notes (e.g. users get/update/delete/send-email are keyed by email address, not a numeric ID), see references/commands.md.

For send-test-message conversation flow details (greeting / follow-up / silence / DTMF), see references/commands.md § Conversation Test API.

Auth

All requests use the header:

Syllable-API-Key: <api-key>

Auth is skipped for help and completion commands. HTTP client timeout is 30 seconds.

Headless / CI auth (v1.7+): the SYLLABLE_API_KEY environment variable, when set, takes priority over ~/.syllable/config.yaml — the CLI runs with no syllable setup at all (CI pipelines, scheduled routines, scripts). For interactive use keep using syllable setup; never echo, log, or hardcode a key when wiring the env var (inject it from a secret store).

Dual Input Pattern

Most create commands support two modes:

1. File mode: --file path/to/body.json — reads a full JSON body from disk
2. Inline flags: Individual flags like --name, --type, etc. — builds a minimal body with default empty maps/arrays for nested fields
3. Stdin: --file - — reads JSON from stdin (useful for piping)

Update commands require --file (no inline flags).

API Patterns

• Endpoints: /api/v1/{resource}/?page=...&limit=...
• Search: &search_fields=<field>&search_field_values=<value>
• Date filters: &start_datetime=ISO8601&end_datetime=ISO8601
• Default page size: 25 items
• Table fallback: If table format parsing fails, falls back to JSON output

Update Commands Are Full Replacements (PUT, Not PATCH)

All update commands send a full PUT request — the server replaces the entire resource. Any field omitted from the update body will be set to null or its default. This means:

• Always start your update body from the full resource JSON (use get <id> -o json first)
• Include all required fields — especially large text fields like context on prompts, which have NOT NULL constraints and will cause a 500 error if omitted
• The pattern is: get → edit → put, not just patch the fields you want to change

Positional ID is enforced (v1.7+). On the body-routed update commands (agents, prompts, custom-messages, language-groups update by id; users by email; tools by name), the positional argument is now injected into the body when missing, and a body carrying a different identifier is a hard error before any request is sent (positional argument "574" conflicts with id=575 in the request body). Pre-1.7, the positional was silently ignored and the body's id decided what got updated — make the two match.

Example for prompts:

# Get the current state first
syllable --env staging prompts get 950 -o json > prompt-update.json

# Edit the file (change tools, llm_config, etc.)
# Then update with the full body
syllable --env staging prompts update 950 --file prompt-update.json

Workflow Tips

• Use --output json to get raw API responses for scripting or piping to jq
• Use --dry-run to preview what API request would be sent before executing
• Use --debug to inspect HTTP request/response details when troubleshooting
• Create/update commands read a JSON body from --file path/to/body.json or --file - for stdin
• List commands default to 25 results per page; use --limit and --page to paginate
• Bulk analysis with JSON list output: prompts list -o json returns full prompt text (context field), agent_count, llm_config, tools, and all metadata for every prompt in a single call. This is far more efficient than calling prompts get on each prompt individually. The same applies to other resources — agents list -o json, tools list -o json, etc. all return complete objects. Use --limit 100 (or higher) to fetch all resources in one request for audits, bulk analysis, or scripting.
• Source and releases: https://github.com/asksyllable/syllable-cli

References

Detailed reference files (loaded on demand, not every session):

• references/gotchas.md — CLI/API gotchas: payload formats, validation rules, shell pitfalls, creation ordering, LLM config
• references/common-patterns.md — CLI recipes: data source wiring, cross-org cloning, tool reuse, variable config, batch testing
• references/payload-examples.md — JSON templates for tool, prompt, agent, and data source payloads
• references/telephony-and-channels.md — Telephony config fields, channel service enums, target modes, email/Twilio config, ReDi bridge phrases, campaign voicemail detection
• references/variables-and-messages.md — Variable syntax (3 formats with missing-value behaviors), system variables, message time-based rules, day-of-week enums
• references/sessions-and-debugging.md — Session fields, transcript structure, tool actions, latency analysis, session-debug commands, Console URL patterns
• references/insights.md — Insights system: folders, tool definitions, tool configs, workflows (lifecycle, conditions, activation), outputs
• references/outbound-campaigns.md — Campaign lifecycle, batch statuses, request statuses, results correlation, variable scoping