CLI reference
The local workflow has three first-level commands: syndroo connect, syndroo publish and syndroo status. An optional syndroo server family deploys and operates a user-owned Cloudflare Worker. Retrying is a mode of syndroo publish, and querying is read-only in syndroo status. Every command and flag on this page is checked against the built CLI when the site is published.
Global flags
These are read before the command, so they work in any position on the line and are never passed to a command.
| Flag | Meaning |
|---|---|
--config | Select the local configuration file. The path must be absolute. Server commands use server --project <directory> instead. |
--json | Print one JSON envelope and never prompt. |
--verbose | Add full identifiers and the reviewed safe diagnostics. Diagnostics are written to stderr, so a JSON stdout stays one document. |
--no-color | Disable colour in human output. NO_COLOR does the same. |
--help | Print usage for the whole CLI, or for one command. |
--version | Print the installed version and the Node.js version that ran it. |
Repeating a global flag is a usage error rather than a silent last-one-wins. A bare syndroo prints the same usage and exits 0 without touching the configuration or creating any state.
syndroo connect
syndroo connect [options] [provider]Starts, resumes or maintains one connection. Exactly one mode per run: a provider positional starts a connection, --update and --disconnect maintain an existing one, and --input reads a whole request document.
| Flag | Meaning |
|---|---|
--label | Name the connection. |
--connection | Reconnect or refresh an existing connection id. |
--from-env | Read the credentials from SYNDROO_CREDENTIALS. |
--credential-file | Read the credentials from one private JSON file. |
--update | Change a connection's label or default flag. |
--disconnect | Remove one stored connection. Never revokes a platform credential. |
--input | Read a machine request document; - reads standard input. |
--redirect-uri <uri> | Choose the OAuth redirect the CLI binds itself. Defaults to a pre-registerable loopback URI; the CLI serves that host, port and path and receives one redirect, which needs a controlling terminal. |
--callback-url <url> | Complete a redirect with the URL the browser landed on. - reads it from standard input; a URL that carries code or state is refused on the command line. |
--default | Mark the connection as the default target. |
--no-default | Clear the default flag. |
--from-env and --credential-file are mutually exclusive, and a resume request is only ever accepted from standard input. A connect step that still needs input reports the pending action and exits 0 instead of blocking; on a terminal the same run prompts for the fields the provider declared. For the OAuth providers (linkedin, threads and mastodon) --redirect-uri names the loopback callback the CLI binds itself and --callback-url - takes the redirected URL on standard input; that local callback path is fixture-tested against local servers only.
syndroo publish
syndroo publish [options]Prepares, executes or retries a publication. Exactly one input source is required, and a request whose type is execute may only come from standard input.
| Flag | Meaning |
|---|---|
--input | Read the request document from a file; - reads standard input. |
--data | Take the request document inline. Never a place for credentials. |
--retry | Retry the eligible targets of an earlier operation. |
--to | Name the connection to retry. Repeatable, one per target. |
--request-id | Give this logical call a stable identity. |
--dry-run | Preview only: no state, no credentials, no network request. |
--yes | Auto-confirm the frozen intent this process just prepared, without a prompt. |
--to requires --retry, and --dry-run refuses a retry. A retry target must be eligible: a delivery whose outcome is unknown is never retried.
syndroo publish --retry <operationId> --to <connectionId> --yes --jsonOn a terminal a prepared document prints the frozen preview and asks Publish to N accounts? [y/N/v]. The accepted answers are y or yes, n or no, and v or view: only an unambiguous y executes the token this process just minted, while n, no, an empty line or end-of-input cancels and sends nothing, and any other answer is not an authorization and asks again. v or view expands the complete frozen preview and asks again; it never re-reads or re-prepares the input and never extends the confirmation window, whose deadline is fixed before the first prompt and measured again on every later answer. Editing the input file after the prepare changes nothing about what is sent. An approval that expired, a connection whose binding changed or a provider that changed refuses the old token instead of reusing it for content or accounts it was not frozen against. --yes skips the prompt but not the frozen-intent checks: it re-mints no credential, bypasses no identity binding, expiry, provider validation or idempotency rule, and creates no second prepare. With --dry-run it stays offline. An explicit execute request already carries its own authorization, so --yes adds nothing there; a retry prepares the selected eligible subset and --yes confirms and executes that same frozen retry.
Execution reports real progress and not a guess. Each observation is one post-commit projection of the stored operation, read back after the write it describes, so a progress line can never show a state that was not durably recorded. Targets run in serial order: while the first target is Publishing the ones queued behind it still read Waiting, and a target only changes when its own durable write lands.
Where the terminal can be redrawn safely the block is redrawn in place with the cursor hidden; anywhere else it becomes an appended log that appends only the status lines that actually changed and finishes with the complete result and the summary. A finish and an interrupt both restore the cursor and drop the resize and abort listeners, so the terminal is left usable either way.
With --json there is no live block at all: no progress, no prompt and no escape sequence reach stdout, which keeps exactly one envelope. The frozen preview and the confirmation prompt are written to the controlling terminal, not to stdout, so a redirected stdout is never the place an answer is typed; --json never prompts, --yes auto-confirms, and a human prepare without --yes needs a writable controlling terminal. Without one it reports the pending result and exits 0 rather than blocking on a read nobody can answer or sending on an answer nobody saw.
The default human view shows at most three content lines and two reason lines per target with one suggested next step, and it hides the internal ids and the confirmation window; --verbose adds them and prints the expiry line only when the expiry is recorded. A target that failed, was only partly sent, is unknown or is not yet finished gets one query command per operation, not one per target: syndroo status --operation <operationId> --verbose. unknown is distinct from not_started: an unknown write may have reached the platform and is never retried automatically, while a target that never started reads as not sent.
syndroo status
syndroo status [options]Read-only. It never creates the state root, never takes a write lock, never reads a secret and never contacts a platform. With no selector it answers the overview.
| Flag | Meaning |
|---|---|
--provider | Ask about one provider; may also filter --connections. |
--connections | List the stored connections. |
--operation | Read one operation by id. |
--operations | Page through the recent operation summaries. |
--limit | Page size for --operations, from 1 to 100. |
--cursor | Opaque cursor for the next --operations page. |
--connections, --operation and --operations are mutually exclusive, --provider cannot be combined with either operation selector, and --limit or --cursor without --operations is a usage error.
syndroo server
server init installs the released @syndroo/cli and @syndroo/cloudflare packages, and installs project-local Wrangler. The workflow is fixture-tested without live Cloudflare, GitHub, Meta or Threads acceptance. Registry publication and product deployment are separate release actions.
Run a Server command from its project, or select the project explicitly with syndroo server --project <directory> <command>. The --project option belongs to server and is written before the subcommand; the installed CLI also accepts it after the leaf command. The published release requires it for connect threads and publish threads, while deploy and doctor already use the current directory. The reviewed fix makes the current directory the default for all of them, so passing the project explicitly stays correct there too. Deployment reuses an existing Wrangler login and does not launch one. The Deploy a server guide covers prerequisites, authorization and the complete first-run sequence.
| Command | What it does |
|---|---|
syndroo server init [directory] | Creates the tracked configs, pinned package manifest and lockfile, sample post and local Git commit. --github OWNER/REPO also creates and pushes a repository; private is the default and public requires an explicit choice. |
syndroo server doctor | Runs read-only project, tool and deployment checks. It does not repair the project or prove OAuth or publication readiness. |
syndroo server deploy --yes | Provisions missing owned resources and deploys the Worker after the user authorizes that target. |
syndroo server --project . connect threads --app-id APP_ID | Completes Threads OAuth and saves the verified connection reference. The App Secret uses hidden input, THREADS_APP_SECRET or --app-secret-stdin. |
syndroo server ci setup github --repo OWNER/REPO --yes | Installs the manual Publish to Threads workflow and configures the scoped GitHub environment without committing, pushing or publishing. |
syndroo server --project . publish threads --input FILE --request-id REQUEST_ID --yes --json | Publishes one strict { "text": string } document with the scoped CI token. Reuse the request ID to recover the same logical publication. |
Exit codes
An exit code describes the local call, not the platform. Exit 0 can still mean a pending authorization or a preview that has not been executed yet.
| Code | Meaning |
|---|---|
0 | Handled as documented. A result may still need confirmation or authorization. |
1 | Internal or durability failure. Side effects are unknown. |
2 | Usage, configuration, authentication or preflight refusal. Nothing was sent. |
4 | A write may have reached the provider and no result is known. |
5 | A human explicitly declined at the confirmation step. Nothing was sent. |
6 | Execution finished and is known not to be fully successful. |
130 | The local process stopped on a signal. Server-side work was not cancelled. |
Related
- Deploy a server for the complete optional Server setup and publication flow.
- Configuration for the file shape and the state root.
- Credentials for the field names per provider.
- Requests and envelopes for every request and result shape.