CLI command reference

This page covers Stacksync CLI 1.0.11. Run stacksync -v to see your version. The CLI keeps itself up to date.

stacksync <command> [options]
stacksync <command> -h

stacksync -h lists every command, including the subcommands of workflow-connector and workflow-module. Each command's -h ends with a link to its section on this page.

SummaryCopy Anchor Link

Commands that run in the connector folder read its stacksync.yml. Outside a connector they stop with No stacksync.yml found. Commands that talk to Stacksync need a login and otherwise stop with Not authenticated. Run 'stacksync login' to set your API key.

loginCopy Anchor Link

stacksync login [--api-key <key>] [--workspace <id>] [--check]

Without options, login asks how to authenticate: Log in via the web opens the browser, and Copy/Paste API key takes a workspace API key. After a web login you choose the default workspace. If a login already exists on this machine, it offers to keep it.

Without a terminal and without an API key, login stops and tells you to pass --api-key.

stacksync login --api-key "$STACKSYNC_API_KEY" --workspace 1234

logoutCopy Anchor Link

stacksync logout

Removes the saved API key and default workspace from this machine. The next command that talks to Stacksync asks you to log in again.

helloCopy Anchor Link

stacksync hello

Shows the welcome screen with the getting-started commands, the same as running stacksync on its own. Use it to confirm the CLI is installed and on your PATH.

updateCopy Anchor Link

stacksync update [--force]

Installs the latest release now. It does nothing when you already have the latest version, unless you pass --force. The CLI keeps itself up to date, so you only need this on version 1.0.10 or earlier: run it once, and later updates are automatic.

workflow-connector createCopy Anchor Link

stacksync workflow-connector create "<name>"

Creates the folder workflows-app-<name> in the current folder from the official connector template. The name is turned into lowercase words joined by hyphens: "Acme CRM" creates workflows-app-acme-crm.

create fills in stacksync.yml:

• app_type is the name in lowercase with underscores, for example acme_crm.
• app_name and app_type_display are the name as you typed it.
• deployment_settings.workspace is your default workspace. If none is set, create asks for one. It is where run tests the connector and where deploy submits it from; it doesn't limit who can use the deployed connector.

When git is installed, it also starts a Git repository with a first commit. It stops if the folder already exists. The project layout is described in Workflow Connector Development Kit.

workflow-connector runCopy Anchor Link

stacksync workflow-connector run [--port <n>] [--sync-build | --no-sync-build]

Runs the connector on your machine and adds it to your workspace as a temporary private connector, so you can use its modules in the workflow builder while you develop.

What run does, in order:

1. Validates stacksync.yml.
2. Copies the project into .stacksync_build/.
3. Uses the active virtual environment, or creates .venv/ in the project, and installs requirements.txt. When the CDK requirement follows a moving version (@v1, @v2, @prod), it reinstalls the CDK so you always have the latest release of that line.
4. Prints the installed CDK version, for example Stacksync CDK 1.1.1 (tracking @v1).
5. Starts the connector on http://127.0.0.1:<port>.
6. Registers the temporary connector in your workspace, in the region of stacksync.yml, and forwards its requests to your machine through a secure connection.

While it runs, every request from Stacksync is handled by the code on your machine and recorded for replay. A request that takes longer than 10 seconds locally times out. Saved file changes are copied into the build and reloaded. Added files are picked up too; after you delete or rename a file, restart run.

Press Ctrl+C to stop. run then removes the temporary connector from the workspace.

run needs Python 3.10 or later. If .venv/ was created with an older Python, delete it and run again.

workflow-connector deployCopy Anchor Link

stacksync workflow-connector deploy

Packages the connector's source and submits it to Stacksync. Unlike run, which keeps the connector on your computer and links it to your workspace only while it runs, a deployed connector is hosted by Stacksync and is available in every Stacksync workspace: see Who can use a deployed connector. A Stacksync reviewer approves each deployment before it is built, so deploy returns as soon as the source is accepted:

Deployment 3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9 submitted for review.
It is built and deployed once a Stacksync reviewer approves it. You will get an email when it ends.

The source package is .stacksync_deployment/source.zip. It leaves out .git, .venv, venv, __pycache__, .stacksync_build, .stacksync_deployment, .logs, .DS_Store and every .env file except .env.example, .env.sample and .env.template. It must be smaller than 32 MiB: list dependencies in requirements.txt instead of including them.

Stacksync refuses the submission when the connector does not meet the connector standard or a deployment rule, and deploy prints the reason. Only one deployment of a connector can wait for review or be in progress at a time. The whole process is described in Deploy a workflow connector.

workflow-connector deploy-statusCopy Anchor Link

stacksync workflow-connector deploy-status <deployment-id>

Prints the current state of a deployment. The id is the 32-character id that deploy printed. Only the person who submitted the deployment can see its status.

workflow-connector replayCopy Anchor Link

stacksync workflow-connector replay <selector> [--port <n>]

Sends a request recorded during run to the connector running locally, and prints the status and response. Use it to debug a module without running the workflow again. run keeps the last 100 requests in .logs/<app name>.json.

--port is the port of the running connector, 2323 by default.

The log contains the request bodies, including connection credentials. It stays on your machine and is never deployed. Keep .logs/ out of version control, as the template's .gitignore does.

workflow-connector cdkCopy Anchor Link

stacksync workflow-connector cdk [ref]

Shows or changes the CDK version in requirements.txt.

Run stacksync workflow-connector run afterwards to install the new version.

workflow-module createCopy Anchor Link

stacksync workflow-module create "<name>"

Adds the module folder modules/<name>/v1/ with schema.py, content.py, execute.py, config.py and context.md. The name is turned into lowercase words joined by underscores: "Create Records" creates modules/create_records/. It stops if the module exists. The new files contain TODO placeholders, which you replace before deploying. Modules are found on disk, so there is nothing to register.

workflow-module deleteCopy Anchor Link

stacksync workflow-module delete ["<name>"]

Deletes modules/<name>/ and all its versions after you confirm. Run it from the connector folder, or from inside the module's folder and leave out the name.

Environment variablesCopy Anchor Link

FilesCopy Anchor Link

All of these except the files in ~/.stacksync are in the template's .gitignore.

Exit codesCopy Anchor Link

Every command exits with 0 on success and 1 on an error, and prints the reason. login --check exits with 1 when you are not logged in, and deploy-status exits with 1 when the deployment failed.