Execute a local iXML or Zymba script on the active linked ZeyOS instance. Run this command from an app containing zeyos.app.json and .zeysdk/sync.json.

Execution Context

run is console execution with application globals. It sends the local source to the instance and executes it there.

• Effects are real. Database writes, mail, and external calls happen, and there is no dry-run mode.
• Your local file runs even if it was never pushed, but anything it includes resolves to assets deployed on the instance.
• The app's namespace and settings are available. There is no user session, no service AUTH context, and no inbound HTTP request, so REQUEST, SELFURL, and VIEW are absent.
• It does not simulate a weblet or a service route. Console requests use PUT, so GET and POST routes in a rest:server block do not match.

Test weblets, services, schedules, and hooks through their real entry points. See Execution Contexts.

Timeouts

Requests time out after 30 seconds by default; set ZEYSDK_REQUEST_TIMEOUT_MS to a positive integer to change this. The timeout ends the client's wait. It does not show that the server stopped, so the script may still be running or may have finished. run is not resent automatically. Check the script's effects before running it again.

Bash

# Run a script asset
zeysdk run [ASSET_PATH] [options]

# Run inline iXML (auto-wrapped in default iXML document)
zeysdk run --ixml '<output>hello</output>' [options]

# Run inline Zymba
zeysdk run --zymba '/* your code */' [options]

# Equivalent short alias
zeysdk run --zy '/* your code */' [options]

Parameters

Parameter	Description	Required	Example
ASSET_PATH	Script path including class directory and filename	Yes, unless one inline option is used	services/daily-backup.ixml

Options

Option	Description	Default
--verbose	Show detailed execution progress and stack traces	false
--clean	Print only console output (no metrics)	false
--unpretty	Use simple metadata formatting for this run	false
--ixml <code>	Run inline iXML (wrapped in default iXML document)	-
--zymba <code>	Run inline Zymba code	-
--zy <code>	Alias for --zymba	-

Input Rules

• File paths must begin with services, resources, weblets, or assets and use .ixml, .zy, or .zymba.
• Paths must remain inside their asset-class directory. Absolute paths, traversal, invalid characters, and symbolic-link components are rejected.
• Supply either ASSET_PATH or exactly one of --ixml, --zymba, and --zy.
• Inline code cannot be empty. iXML fragments are inserted into the default iXML wrapper; a complete iXML document is used unchanged.
• A file does not need a manifest asset entry, but it must exist locally and be readable.

Execution Results

The command outputs detailed execution metrics:

Bash

=== Run Results ===
Context
  Platform | sdk-alpha (https://cloud.zeyos.com/sdk-alpha/)
  Engine   | iXML
Metrics
  Load Time      | 1.2 ms
  Execution Time | 45.3 ms
  Memory Usage   | 2.5 MB
  Output Size    | 128 KB
Response
  HTTP Status | 200
Output
  Operation completed successfully

Metric	Description	Format
Platform	Active linked platform	String
Load Time	Script loading duration	milliseconds/seconds
Execution Time	Processing duration	milliseconds/seconds
Memory Usage	Peak memory consumption	Bytes/KB/MB/GB
Output Size	Result data size	Bytes/KB/MB/GB
Engine	Execution engine version	String
Output	Script execution result	String
Debug Output	Debug information	String
Server-reported execution errors are written to standard error and return a nonzero exit status instead of rendering a results block.

Examples

Bash

# Run a service script
zeysdk run services/backup.ixml --verbose
# Output:
# Input validation completed.
# Loading sync info and package info.
# Making REST call to run file on the server.
# Run completed successfully.
# === Run Results ===
# Context
#   Platform | sdk-alpha (https://cloud.zeyos.com/sdk-alpha/)
#   Engine   | iXML
# Metrics
#   Load Time      | 0.8 ms
#   Execution Time | 123.4 ms
#   Memory Usage   | 1.2 MB
# Output
#   Backup completed successfully

# Run a Zymba weblet script (`.zymba` is also accepted)
zeysdk run weblets/dashboard.zy
# Output:
# === Run Results ===
# Context
#   Platform | sdk-alpha (https://cloud.zeyos.com/sdk-alpha/)
# Metrics
#   Load Time      | 1.1 ms
#   Execution Time | 67.2 ms
#   Memory Usage   | 3.4 MB
# Output
#   Dashboard rendered successfully

# Run inline iXML
zeysdk run --ixml '<output>Hello</output>'

# Run inline Zymba with the short alias
zeysdk run --zy 'return "Hello";'

# Print only script output
zeysdk run services/backup.ixml --clean

# Force simple metadata output
zeysdk run services/backup.ixml --unpretty

Error Handling

Error	Description	Resolution
Invalid asset class	Wrong type specified	Use correct asset class
Missing sync.json	App is not linked	Run zeysdk link first
Invalid sync.json	Linked instance lacks id or url	Relink the instance
Missing script	Local file is missing or unreadable	Check the path and permissions
Unsafe path	Path escapes its asset directory or uses a symbolic link	Use an in-app path
Invalid script type	Wrong extension	Use .ixml, .zy, or .zymba
Invalid usage	Missing input, multiple inline flags, or mixed path and inline input	Supply exactly one input source
Authentication error	Token expired	Auto-relinks
Execution error	Server returned a runtime error	Check standard error; add --verbose for a stack trace

By default, stack traces from execution errors are hidden. Use --verbose to include them. --clean writes only script console output to standard output; errors still go to standard error and exit nonzero. When --clean is present, progress messages are suppressed.

Default output style is pretty. Set a global default under zeysdk configure -> Run Output Style, or override per command with --unpretty.

Compile Scripts (zeysdk compile)

Compile a local or inline iXML/Zymba script on the linked instance without executing it.

Compilation is not offline: the command transmits the source to the instance's authenticated compiler, so it needs a linked app, a valid token, and network access. A successful compile does not show that database identifiers exist, that include targets are deployed, or that the code behaves correctly at runtime. See Verification Checkpoints.

Bash

zeysdk compile [ASSET_PATH] [options]
zeysdk compile --ixml '<output>Hello</output>'
zeysdk compile --zy 'return "Hello";'

ASSET_PATH and inline input follow the same extension, path-safety, and mutual-exclusion rules as run. Compile also requires both the app manifest and a valid linked sync file.

Option	Description
--verbose	Show validation, API, and completion progress
--ixml <code>	Compile inline iXML, wrapping a fragment in the default document
--zymba <code>	Compile inline Zymba
--zy <code>	Alias for --zymba
--phpout [OUTPUT_FILE]	Print returned PHP to standard output, or write it to OUTPUT_FILE
--intermediate	Request and print returned intermediate Z-code

Bash

# Show compilation summary
zeysdk compile services/backup.ixml

# Print only the returned PHP when available
zeysdk compile services/backup.ixml --phpout

# Write returned PHP to a file
zeysdk compile services/backup.ixml --phpout compiled.php

# Request and display intermediate Z-code
zeysdk compile services/backup.ixml --intermediate

A server-reported compilation error is written to standard error and exits nonzero. It is checked before PHP output, so --phpout OUTPUT_FILE does not write code from an error response. A local output-file error also exits nonzero.

Lint Project Scripts (zeysdk lint)

Compile eligible project .ixml, .zy, and .zymba files and summarize each result. The file set comes from the app manifest plus standard local settings files.

Bash

zeysdk lint [--all] [--verbose]

By default, lint fetches server state and checks locally present scripts that differ from the last synchronized state. --all checks every eligible locally present script without first fetching server state. The command requires a linked app and rejects unreadable or unsafe manifest paths rather than silently skipping them.

Like compile, lint transmits source to the remote compiler and does not execute it. --all skips the server-state comparison, not the compile requests.

Each script is reported as OK or ERROR. Compilation and network failures are reported per file; the command exits with status 1 if any file fails. Finding no eligible scripts is informational and exits successfully, but it is not a pass: nothing was checked. Scripts that are not registered in the manifest are not selected, so compile those by path.