Syndroodocs
WebsiteGitHubOverview

CLI reference

Three first-level commands and no others: syndroo connect, syndroo publish and syndroo status. 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.

FlagMeaning
--configSelect the configuration file. The path must be absolute.
--jsonPrint one JSON envelope and never prompt.
--verboseAdd diagnostics, such as the request id a call recorded.
--no-colorDisable colour in human output. NO_COLOR does the same.
--helpPrint usage for the whole CLI, or for one command.
--versionPrint the candidate 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.

FlagMeaning
--labelName the connection.
--connectionReconnect or refresh an existing connection id.
--from-envRead the credentials from SYNDROO_CREDENTIALS.
--credential-fileRead the credentials from one private JSON file.
--updateChange a connection's label or default flag.
--disconnectRemove one stored connection. Never revokes a platform credential.
--inputRead 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.
--defaultMark the connection as the default target.
--no-defaultClear 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.

FlagMeaning
--inputRead the request document from a file; - reads standard input.
--dataTake the request document inline. Never a place for credentials.
--retryRetry the eligible targets of an earlier operation.
--toName the connection to retry. Repeatable, one per target.
--request-idGive this logical call a stable identity.
--dry-runPreview only: no state, no credentials, no network request.

--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 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.

FlagMeaning
--providerAsk about one provider; may also filter --connections.
--connectionsList the stored connections.
--operationRead one operation by id.
--operationsPage through the recent operation summaries.
--limitPage size for --operations, from 1 to 100.
--cursorOpaque 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.

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.

CodeMeaning
0Handled as documented. A result may still need confirmation or authorization.
1Internal or durability failure. Side effects are unknown.
2Usage, configuration, authentication or preflight refusal. Nothing was sent.
4A write may have reached the provider and no result is known.
5A human explicitly declined at the confirmation step. Nothing was sent.
6Execution finished and is known not to be fully successful.
130The local process stopped on a signal. Server-side work was not cancelled.