Zillowe Docs - CLI Reference

The Zoko CLI (zoko-cli) provides several commands for working with Zoko files.

Installation

You can install Zoko CLI using Zoi:

zoi install @zillowe/zoko

Install from Source

git clone https://github.com/akuolwa/zoko.git
cd zoko
cargo build --release

The binary will be available at target/release/zoko-cli.

Install via Cargo

cargo install zoko-cli

Global Options

zoko-cli [OPTIONS] <COMMAND>

Options

-h, --help: Print help information
-V, --version: Print version information

Commands

parse

Parse a .zo file and output as JSON or YAML.

zoko-cli parse [OPTIONS] <FILE>

Arguments

<FILE>: Input .zo file path

Options

-o, --output <FILE>: Output file (stdout if not specified)
--pretty: Pretty print JSON output (default: true)
--yaml: Output as YAML instead of JSON

Examples

# Parse and output to stdout as JSON
zoko-cli parse config.zo

# Parse and output to file
zoko-cli parse config.zo --output config.json

# Parse without pretty printing
zoko-cli parse config.zo --no-pretty

# Parse and output as YAML
zoko-cli parse config.zo --yaml

# Parse and output as YAML to file
zoko-cli parse config.zo --yaml --output config.yaml

validate

Validate a .zo file without outputting the parsed content.

zoko-cli validate <FILE>

Arguments

<FILE>: Input .zo file path

Exit Codes

0: File is valid
1: File has syntax errors

Examples

# Validate a file
zoko-cli validate config.zo

# Output: ✓ File is valid: config.zo

fmt

Format a .zo file (pretty print).

zoko-cli fmt [OPTIONS] <FILE>

Arguments

<FILE>: Input .zo file path

Options

-o, --output <FILE>: Output file (overwrites input if not specified)
-c, --check: Check if file is formatted correctly without writing

Formatting Rules

The formatter:

Preserves entry order (using IndexMap)
Maintains original structure and nesting
Standardizes indentation
Normalizes spacing and punctuation
Keeps comments and their placement

Examples

# Format file in-place
zoko-cli fmt config.zo

# Format to different file
zoko-cli fmt config.zo --output formatted.zo

# Check if file needs formatting (without modifying)
zoko-cli fmt --check config.zo

# Output: ✓ File is properly formatted: config.zo
# Or: ✗ File is not properly formatted: config.zo

check

Check a .zo file for syntax errors.

zoko-cli check <FILE>

Arguments

<FILE>: Input .zo file path

Exit Codes

0: File has no syntax errors
1: File has syntax errors

Examples

# Check a file for errors
zoko-cli check config.zo

# Output: ✓ Check passed: config.zo
# Or: ✗ Check failed: <error message>

Common Workflows

Convert Zoko to JSON

zoko-cli parse input.zo --output output.json --pretty

Convert Zoko to YAML

zoko-cli parse input.zo --yaml --output output.yaml

Format All Zoko Files

# Format single file
zoko-cli fmt config.zo

# Format multiple files
find . -name "*.zo" -exec zoko-cli fmt {} \;

Validate Configuration Files

# Validate before deployment
zoko-cli validate config.zo

Check Format in CI/CD

# Check if files are properly formatted in CI
zoko-cli fmt --check config.zo

Error Messages

Parse Errors

✗ Parse error: Expected { expected: "valid zoko input", found: "..." }

Common causes:

Invalid syntax
Unclosed brackets or quotes
Invalid number formats

Validation Errors

✗ Validation failed: <error details>

Common causes:

Syntax errors in the file
Invalid escape sequences
Malformed structures

Format Check Errors

✗ File is not properly formatted: <file path>

Solution: Run zoko-cli fmt <file> to fix formatting issues.

Tips and Best Practices

Use Validation in Scripts

#!/bin/bash
# Validate config before starting application
if zoko-cli validate config.zo; then
  echo "Configuration is valid"
else
  echo "Configuration is invalid"
  exit 1
fi

Format Files Before Committing

# Add pre-commit hook to format files
zoko-cli fmt *.zo
git add *.zo

Use Check in CI Pipelines

# In your CI pipeline
- name: Check formatting
  run: zoko-cli fmt --check config.zo

Pretty Print for Human Reading

# Pretty print JSON for easier reading
zoko-cli parse config.zo --pretty

Exit Code Reference

Exit Code	Meaning
0	Success
1	Error (parse error, validation failure, format check failed)

File Extensions

.zo: Standard Zoko file extension
.json: Output JSON files (when using parse command)
.yaml, .yml: Output YAML files (when using parse command with --yaml flag)

CLI Reference

Zillowe Foundation

On this page