tailor

Tailor Platform SDK - The SDK to work with Tailor Platform

Usage

tailor <command> [options]

Global Options

Option	Alias	Description	Required	Default
--env-file <ENV_FILE>	-e	Path to the environment file (error if not found)	No	-
--env-file-if-exists <ENV_FILE_IF_EXISTS>	-	Path to the environment file (ignored if not found)	No	-
--verbose	-	Enable verbose logging	No	false
--json	-j	Output as JSON	No	false

Progress and Detailed Logs

generate and deploy show service progress and failures on stderr. Pass --verbose to include individual loaded files, plugin table changes, and generated file paths. Generation reports completion for each plugin that finishes processing its output files.

JSON Output

For commands that return structured results, passing --json writes one parseable JSON document to stdout on success. Empty successful result sets are emitted as JSON values such as [], not as human-readable text or empty stdout.

Commands that only perform side effects and do not define a structured result may leave stdout empty even when --json is passed.

Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing, a command failure under --json emits a JSON error envelope to stderr. Failures you can act on — an invalid or missing option, a resource that does not exist, an invalid configuration, or an unmet precondition — carry a stable error.code such as PROFILE_NOT_FOUND, TAILORDB_NAMESPACE_NOT_FOUND, or MIGRATION_SCRIPT_REQUIRED. Where a remediation exists, the envelope also includes error.suggestion, error.help (the --help invocation for the failing command), error.next (a runnable command), or error.context. UNEXPECTED_ERROR marks failures without a dedicated code, including SDK-internal errors. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain an error object.

Authentication failures distinguish missing credentials (AUTH_TOKEN_NOT_FOUND), a missing saved user (AUTH_USER_NOT_FOUND), an expired token (AUTH_TOKEN_EXPIRED), and a failed token refresh (AUTH_TOKEN_REFRESH_FAILED). Login recovery preserves the selected profile. For saved identities, the next step opens login help so you can reuse the original browser or machine-user login method. Permission and connection failures include guidance in error.suggestion; API failures also identify the operation and affected resources in error.context.

If deployment fails and saving recovery metadata also fails, DEPLOY_METADATA_RECOVERY_FAILED includes separate error.context.apply and error.context.recovery errors, each retaining its code and available recovery information. Inspect the current resource state before retrying: some writes may have completed. --verbose --json additionally includes stack traces for both causes.

Generation hook failures use PLUGIN_GENERATION_FAILED. The error includes the failed hook and each failing plugin's ID and error in error.context.failures; successful plugins are excluded from that list.

Verbose Output

Use --verbose to include debug diagnostics and error stack traces. DEBUG=true or RUNNER_DEBUG=1 also enables verbose output, including stacks in JSON errors. GitHub Actions sets RUNNER_DEBUG=1 when debug logging is enabled, so the same command automatically includes these details in a debug run. These settings do not enable JSON output; pass --json separately.

Capture the original failure's stderr and exit code before retrying. Argument parsing and failures before the CLI starts may produce plain text even with --json. A failed deployment may have already applied changes, so inspect its output before deciding to run it again.

GitHub Actions Annotations

When GITHUB_ACTIONS is exactly true, a command that ends in failure also writes one ::error:: workflow command to stderr, so the failure appears as an annotation on the run instead of only inside the scrolled log. The annotation repeats what the CLI already prints: its title is the error code (AUTH_TOKEN_NOT_FOUND, PLUGIN_GENERATION_FAILED, ...), and its body carries the same details, suggestion, and next action. Colors are stripped and newlines are encoded, so the annotation is a single line.

Exactly one annotation is written per failed command, and only for the failure that ends it. Warnings and individually reported problems stay plain stderr output. The bundled CLI plugins (seed, setup, tailordb-erd) annotate their failures the same way. A command that exits without reporting through the CLI's error path, such as one relaying a failed remote execution, writes no annotation.

Set TAILOR_GITHUB_ACTIONS_ANNOTATIONS=false (also off, no, or 0) to turn annotations off. Passing --json also suppresses them, so a workflow step that parses --json output gets only the error envelope on stderr. The flag is honored even when the command fails during argument parsing, before the envelope itself becomes available.

An annotation does not by itself fail a step: the step still fails on the CLI's exit code, which is unchanged. Workflows that already echo their own ::error:: around the CLI keep working; those messages describe the workflow's own checks, which can fail even when the CLI succeeds.

When the failure has a known source, the annotation carries it: seed validate reports the offending JSONL file and line, and a rejected config reports its file — or, when the config or a file it imports cannot be parsed, that file and the line it failed on. Locations are written relative to GITHUB_WORKSPACE; a file outside it is annotated without a location rather than with a path the runner cannot resolve.

For a JSONL file containing a blank line, the annotation's line and the line printed in the report text differ: the annotation counts every line in the file, while the printed line counts only the records. The annotation points at the row as an editor numbers it.

generate and deploy do not group their per-service progress.

Common Options

The following options are available for most commands:

Option	Short	Description
--workspace-id	-w	Workspace ID (for deployment commands)
--profile	-p	Workspace profile
--config	-c	Path to Tailor config file
--yes	-y	Skip confirmation prompts

Environment File Loading

Both --env-file and --env-file-if-exists can be specified multiple times and follow Node.js --env-file behavior:

• Variables already set in the environment are not overwritten
• Later files override earlier files
• --env-file files are loaded first, then --env-file-if-exists files

# Load .env (required) and .env.local (optional, if exists)
tailor deploy --env-file .env --env-file-if-exists .env.local

# Load multiple files
tailor deploy --env-file .env --env-file .env.production

Environment Variables

You can use environment variables to configure workspace and authentication:

Variable	Description
TAILOR_PLATFORM_WORKSPACE_ID	Workspace ID for deployment commands
TAILOR_PLATFORM_ORGANIZATION_ID	Organization ID for organization commands
TAILOR_PLATFORM_FOLDER_ID	Folder ID for folder commands
TAILOR_PLATFORM_TOKEN	Authentication token (alternative to login)
TAILOR_PLATFORM_PROFILE	Workspace profile name
TAILOR_CONFIG_PATH	Path to Tailor config file
TAILOR_DTS_PATH	Output path for generated tailor.d.ts type definition file
TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID	Client ID for login --machine-user
TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET	Client secret for login --machine-user
TAILOR_PLATFORM_MACHINE_USER_NAME	Default machine user name for query, workflow start, function run, machineuser token
TAILOR_PLATFORM_URL	Platform API base URL. Saved into profiles created with profile create --platform-url
TAILOR_PLATFORM_OAUTH2_CLIENT_ID	OAuth2 client ID for user login. Saved into profiles created with profile create --oauth2-client-id
TAILOR_PLATFORM_CONSOLE_URL	Console base URL. Saved into profiles created with profile create --console-url
TAILOR_BUNDLE_CONCURRENCY	Max concurrent bundle workers for deploy (resolvers/executors/workflows). Defaults to CPU count
TAILOR_APPLY_CONCURRENCY	Max concurrent platform RPCs during apply/deploy. Defaults to 16
VISUAL / EDITOR	Preferred editor for commands that open files (e.g., vim, code, nano)
TAILOR_GITHUB_ACTIONS_ANNOTATIONS	GitHub Actions failure annotations: on (default) or off
TAILOR_CRASH_REPORTS_LOCAL	Local crash log writing: on (default) or off
TAILOR_CRASH_REPORTS_REMOTE	Automatic crash report submission: off (default) or on

Authentication Token Priority

Token resolution follows this priority order:

1. TAILOR_PLATFORM_TOKEN environment variable
2. Profile specified via --profile option or TAILOR_PLATFORM_PROFILE
3. Current user from platform config (~/.config/tailor-platform/config.yaml)

Config-backed login tokens are scoped to the Platform API URL. Profiles with --platform-url use the token saved for that URL, so switching profiles can also switch between Platform API environments.

Workspace ID Priority

Workspace ID resolution follows this priority order:

1. --workspace-id command option
2. TAILOR_PLATFORM_WORKSPACE_ID environment variable
3. Profile specified via --profile option or TAILOR_PLATFORM_PROFILE

CLI Plugins

WARNING

CLI plugins are a beta feature. The dispatch behavior and the set of injected environment variables may change in a future release.

You can extend the CLI with external plugins, similar to gh extensions. When you run a command that is not a built-in, the CLI looks for an executable named tailor-<name> and runs it, forwarding the remaining arguments:

# Runs the `tailor-hello` executable with: world --loud
tailor hello world --loud

This is how the @tailor-platform/sdk-plugin-seed package provides the seed commands:

# Runs `tailor-seed` with: apply
tailor seed apply

This also works under a built-in command group. The command path is joined with hyphens, so a plugin nested under tailordb is named tailor-tailordb-erd. This is how the @tailor-platform/sdk-plugin-tailordb-erd package provides the tailordb erd commands:

# Runs `tailor-tailordb-erd` with: export
tailor tailordb erd export

Resolution rules:

• Built-ins always win. A plugin is only used when no built-in command matches.
• A command that takes its own arguments is never replaced. Plugin dispatch applies only to command groups (commands that just route to subcommands). A command that performs its own action — including one that accepts a positional argument — always runs itself, so a plugin can never shadow an argument value.
• Lookup order: the project's node_modules/.bin (nearest first, walking up from the current directory), then your PATH. So a plugin installed as a project dev-dependency takes precedence over a globally installed one.
• Global flags reach the plugin from either side. tailor --json tailordb erd export and tailor tailordb erd export --json both forward --json, and likewise --verbose and the --env-file options. A flag typed before the plugin name is consumed by the host CLI first and then forwarded, so when the same flag appears on both sides the later one wins. A flag the host does not define — including one only some commands declare, such as --profile — still has to be typed after the plugin's own subcommand. --help and --version are answered by the host CLI and never dispatch a plugin.

Because resolution is based on node_modules/.bin and PATH, any package manager that populates node_modules/.bin works for project-local plugins — npm, pnpm (its content-addressable store is transparent here), Bun, and Yarn Classic. The exception is Yarn Plug'n'Play, which does not create a node_modules directory: install such plugins globally so they resolve via PATH, or use Yarn's nodeLinker: node-modules setting.

Run tailor plugin list to see which plugins are discovered and where they resolve from.

Context passed to plugins

Before running a plugin, the CLI injects the current Tailor Platform context as environment variables so the plugin does not need to re-implement authentication or re-resolve the active workspace:

Variable	Description
TAILOR_PLATFORM_TOKEN	A valid access token (refreshed if needed). Omitted when not logged in.
TAILOR_PLATFORM_URL	The Tailor Platform endpoint in effect
TAILOR_PLATFORM_OAUTH2_CLIENT_ID	The OAuth2 client ID in effect, for plugins that run their own auth flow
TAILOR_PLATFORM_WORKSPACE_ID	The resolved workspace ID, when one can be determined
TAILOR_PLATFORM_USER	The active user (email when known), when logged in
TAILOR_CONFIG_PATH	Path to the resolved Tailor config file, when found
TAILOR_VERSION	The tailor version that invoked the plugin
TAILOR_BIN	Path to the tailor executable, for calling back into the CLI

The token, workspace ID, and user are best-effort: whatever the current context can resolve is injected, and auth-free plugins still run when you are not logged in. A long-running plugin (or one started on its own) can obtain a fresh token at any time with tailor auth token, which prints a valid access token to stdout, refreshing it first if it has expired.

Commands

Application Commands

Commands for managing Tailor Platform applications (work with tailor.config.ts).

Command	Description
init	Initialize a new project using create-sdk.
generate	Generate files using Tailor configuration.
deploy	Deploy your application by applying the Tailor configuration.
remove	Remove all resources managed by the application from the workspace.
show	Show information about the deployed application.
open	Open Tailor Platform Console.
api	Call Tailor Platform API endpoints directly.
api inspect	Print the input message tree of an OperatorService endpoint.
api list	List all invocable OperatorService methods.

TailorDB Commands

Commands for managing TailorDB tables, data, and schema migrations.

Command	Description
tailordb	Manage TailorDB tables and data.
tailordb truncate	Truncate (delete all records from) TailorDB tables.
tailordb migration	Manage TailorDB schema migrations.
tailordb migration generate	Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.
tailordb migration rebaseline	Collapse the full migration history into a new 0000 baseline.
tailordb migration script	Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.
tailordb migration set	Set migration checkpoint to a specific number.
tailordb migration status	Show the current migration status for TailorDB namespaces, including applied and pending migrations.
tailordb migration sync	Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).
tailordb migration test	Test pending migrations with seed fixtures or cloned data in a temporary workspace.
tailordb migration validate	Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found.

Query Commands

Run ad-hoc SQL/GraphQL queries or enter the interactive REPL.

Command	Description
query	Run SQL/GraphQL query.

User & Auth Commands

Commands for authentication and user management.

Command	Description
login	Login to Tailor Platform.
logout	Logout from Tailor Platform.
auth	Authentication helpers for scripts and plugins.
auth status	Show the active Tailor Platform authentication status without printing tokens.
auth token	Print a valid Tailor Platform access token to stdout, refreshing it first if expired.
user	Manage Tailor Platform users.
user current	Show current user.
user list	List all users.
user pat	Manage personal access tokens.
user pat create	Create a new personal access token.
user pat delete	Delete a personal access token.
user pat list	List all personal access tokens.
user pat update	Update a personal access token (delete and recreate).
user switch	Set current user.

Organization Commands

Commands for managing organizations and folders.

Command	Description
organization	Manage Tailor Platform organizations.
organization folder	Manage organization folders.
organization folder create	Create a new folder in an organization.
organization folder delete	Delete a folder from an organization.
organization folder get	Show detailed information about a folder.
organization folder list	List folders in an organization.
organization folder update	Update a folder's name.
organization get	Show detailed information about an organization.
organization list	List organizations you belong to.
organization tree	Display organization folder hierarchy as a tree.
organization update	Update an organization's name.

Workspace Commands

Commands for managing workspaces and profiles.

Command	Description
workspace	Manage Tailor Platform workspaces.
workspace app	Manage workspace applications
workspace app health	Check application schema health
workspace app list	List applications in a workspace
workspace create	Create a new Tailor Platform workspace.
workspace delete	Delete a Tailor Platform workspace.
workspace get	Show detailed information about a workspace
workspace list	List all Tailor Platform workspaces.
workspace prune	Delete stale temporary workspaces, by name and age or by the expiry each recorded at creation.
workspace restore	Restore a deleted workspace
workspace ttl	Manage when a workspace becomes prunable.
workspace ttl clear	Drop a workspace's recorded prune expiry.
workspace ttl set	Record when a workspace becomes prunable, replacing any expiry it already records.
workspace user	Manage workspace users
workspace user invite	Invite a user to a workspace
workspace user list	List users in a workspace
workspace user remove	Remove a user from a workspace
workspace user update	Update a user's role in a workspace
profile	Manage workspace profiles (user + workspace combinations).
profile create	Create a new profile.
profile delete	Delete a profile.
profile list	List all profiles.
profile update	Update profile properties.

Auth Resource Commands

Commands for managing Auth service resources.

Command	Description
authconnection	Manage auth connections.
authconnection authorize	Authorize an auth connection via OAuth2 flow.
authconnection delete	Delete an auth connection entirely.
authconnection list	List all auth connections.
authconnection open	Open the auth connections page in the Tailor Platform Console.
authconnection revoke	Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it).
machineuser	Manage machine users in your Tailor Platform application.
machineuser list	List all machine users in the application.
machineuser token	Get an access token for a machine user.
oauth2client	Manage OAuth2 clients in your Tailor Platform application.
oauth2client list	List all OAuth2 clients in the application.
oauth2client get	Get OAuth2 client credentials (including client secret).

Workflow Commands

Commands for managing workflows and executions.

Command	Description
workflow	Manage workflows and workflow executions.
workflow list	List all workflows in the workspace.
workflow get	Get workflow details.
workflow start	Start a workflow execution.
workflow wait	Wait for a workflow execution.
workflow executions	List or get workflow executions.
workflow resume	Resume a failed or pending workflow execution.

Function Commands

Commands for managing function registries and viewing function execution logs.

Command	Description
function	Manage functions
function get	Get a function registry by name
function list	List function registries in a workspace
function logs	List or get function execution logs.
function run	Run a function on the Tailor Platform server without deploying.
function script	Scaffold a one-off script to run with function run.

Executor Commands

Commands for managing executors and executor jobs.

Command	Description
executor	Manage executors
executor list	List all executors
executor get	Get executor details
executor jobs	List or get executor jobs.
executor trigger	Trigger an executor manually.
executor webhook	Manage executor webhooks
executor webhook list	List executors with incoming webhook triggers

Secret Commands

Commands for managing secrets and vaults.

Command	Description
secret	Manage Secret Manager vaults and secrets.
secret create	Create a secret in a vault.
secret delete	Delete a secret in a vault.
secret list	List all secrets in a vault.
secret update	Update a secret in a vault.
secret vault	Manage Secret Manager vaults.
secret vault create	Create a new Secret Manager vault.
secret vault delete	Delete a Secret Manager vault.
secret vault list	List all Secret Manager vaults in the workspace.

Static Website Commands

Commands for managing and deploying static websites.

Command	Description
staticwebsite	Manage static websites in your workspace.
staticwebsite deploy	Deploy a static website from a local build directory.
staticwebsite list	List all static websites in a workspace.
staticwebsite domain	Manage custom domains for static websites.
staticwebsite domain get	Get details of a custom domain.
staticwebsite domain list	List custom domains for a static website.
staticwebsite get	Get details of a specific static website.

Crash Report Commands

Commands for managing crash reports.

Command	Description
crashreport	Manage crash reports.
crashreport list	List local crash report files.
crashreport send	Submit a crash report to help improve the SDK.

Upgrade Commands

Commands for upgrading SDK versions with automated code migration.

Command	Description
upgrade	Run codemods to upgrade your project to a newer SDK version.

Skills Commands

Commands for managing Tailor SDK agent skills.

Command	Description
skills	Manage Tailor SDK agent skills.
skills add	Install Tailor SDK agent skills.
skills list	List Tailor SDK agent skills.
skills remove	Remove installed Tailor SDK agent skills.
skills sync	Remove and reinstall Tailor SDK agent skills.

Plugin Commands

Discover and inspect CLI plugins (external tailor-<name> executables).

Command	Description
plugin	Manage and inspect CLI plugins (beta).
plugin list	List discovered plugins (executables named <cli>-<name> on PATH or node_modules/.bin).

Completion

Generate shell completion scripts for bash, zsh, and fish.

Command	Description
completion	Generate shell completion script