---
title: "Debugging and Compilation"
description: "Run, compile, and lint iXML and Zymba with the ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/debugging"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/debugging.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/debugging/index.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Debugging and Compilation

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](https://www.zeyos.com/ixml/ixml-guide/development-environment/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](https://www.zeyos.com/ixml/ixml-guide/development-environment/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.