CLI and quick reference

Last updated: 2026-10-14Converting to JSON, freezing an active config, and the whole syntax on one screen.

CLI and quick reference

Mirrored from the format repository — docs/spec/SPECIFICATION_EN.md, SYNX 3.7.4. Changes are made there.

Conversion to JSON (optional)

📎 JSON conversion is an optional feature. It's only needed if you want to pass data to a system that exclusively understands JSON (third-party APIs, legacy code, etc.).

6.1 Via VS Code (SYNX Extension)

If the SYNX for VS Code extension is installed:

  1. Open a .synx file
  2. Right-click on the file
  3. Select "Convert to JSON"
  4. A .json file will appear alongside

6.2 Via Terminal (CLI)

bash
# Convert to JSON and print to console
synx to-json config.synx

# Convert and save to file
synx to-json config.synx -o config.json

# Freeze an !active config into a static .synx (without functions)
synx freeze active_config.synx -o static_config.synx

6.3 Programmatically (if you really need to)

python
import json
from synx import Synx

data = Synx.load('config.synx')
json_string = json.dumps(data, ensure_ascii=False, indent=2)
javascript
const Synx = require('@aperturesyndicate/synx-format');
const data = Synx.loadSync('config.synx');
const jsonString = JSON.stringify(data, null, 2);

But again: this is not needed to work with SYNX. Your code reads .synx directly.

Quick Reference

KEY VALUE                        -> simple pair
key                              -> empty object (group)
  nested_key value               -> nesting (2 spaces)
key |                            -> multiline text
  line 1                           (block)
  line 2
list                             -> list
  - item 1
  - item 2
# comment                       -> single-line comment
// comment                      -> single-line comment

--- Directives ----------------------------------
!active                          -> enable markers + constraints
!lock                            -> mark document read-only
!include ./file.synx             -> include at root level
!tool                            -> tool-call envelope
!schema                          -> JSON Schema export
!llm                             -> LLM metadata flag

--- Markers (require !active) -------------------
key:env VAR                      -> environment variable
key:env:default:X VAR            -> env with fallback
key:calc A * B                   -> arithmetic
key:alias other_key              -> reference to another key
key:secret value                 -> hidden value
key:default dark                 -> default value
key:random                       -> random item from list
key:random 70 20 10              -> weighted random
key:unique                       -> list deduplication
key:include ./file.synx          -> include file
key:import ./file.synx           -> alias for :include
key:template Hello, {name}!      -> string interpolation
key:split red, green, blue       -> string to array
key:join:slash                   -> array to string
key:geo                          -> value by region
key:ref:calc:*2 base             -> resolve and chain
key:i18n                         -> translation by locale
key:clamp:0:100 150              -> numeric clamping
key:round:2 19.999               -> numeric rounding
key:format:%.2f 19.9             -> printf formatting
key:map:lookup_key               -> lookup table
key:once:uuid                    -> generate once, cache
key:version:>=:1.0.0 ver         -> version comparison
key:watch ./flags.synx           -> read external file
key:fallback:./default.synx path -> file fallback
key:spam:5:60 endpoint           -> rate limiting
key:prompt:label subtree         -> LLM prompt label
key:vision ./photo.png           -> image metadata
key:audio ./clip.mp3             -> audio metadata
key:inherit parent               -> object inheritance

--- Constraints (require !active) ---------------
key[min:N, max:N]                -> length/value constraints
key[type:int]                    -> data type
key[required]                    -> required field
key[enum:a|b|c]                  -> allowed values
key[pattern:regex]               -> regex validation
key[readonly]                    -> read-only
CLI and quick reference | AS Docs