CLI

The Schematify CLI (schematify) is a command-line tool for managing graph documents on your Schematify server. Standalone binaries for Linux, macOS, and Windows are available from the Document Manager’s CLI & Agent Setup page or the CLI installation guide.

AI agents use the CLI through Agent Skills, which teach them how to operate these commands and create valid graph documents.

Setup

For the hosted Schematify service, no setup step is required. The CLI uses the hosted Schematify configuration by default, so you can authenticate immediately:

schematify login

schematify login opens a browser-based device flow.

Run schematify setup only when you need to point the CLI at a custom Schematify VM or another non-default deployment. The interactive wizard prompts for your Schematify host and discovers the organisation details from that instance.

schematify setup

Core commands

list

List all schemas on the server.

schematify list
schematify ls          # alias
schematify list --json # structured output for scripting

Schemas are numbered in the output. You can use these reference numbers in place of full IDs in subsequent commands.

push

Upload a graph document to the server. Validates against the Schematify schema before uploading.

schematify push schema.json
schematify push schema.yaml
cat schema.json | schematify push -   # from stdin

Supports both JSON and YAML. Use -f yaml to explicitly set the format when it can’t be inferred.

pull

Download a schema from the server.

schematify pull my-schema              # saves to my-schema.json
schematify pull my-schema -f yaml      # saves as YAML
schematify pull 1                      # by reference number
schematify pull                        # interactive selection
schematify pull my-schema --print      # output to stdout

delete

Remove a schema from the server.

schematify delete my-schema
schematify rm my-schema -f             # skip confirmation
schematify delete 1                    # by reference number

rename

Rename a schema on the server.

schematify rename my-schema "Production Architecture"
schematify rename --select "Production Architecture"

validate

Validate a local schema file without uploading. Useful for checking documents before pushing.

schematify validate schema.json
schematify check schema.yaml           # alias

Scriptable graphs

For a full guide, see Scriptable Graphs.

Run a TypeScript graph script in the CLI sandbox:

schematify run graph.ts
schematify run graph.ts --max-duration 30s
schematify dry-run graph.ts              # preview writes as JSON lines

schematify run executes with real publish behaviour: publish() and channel sends write to the server. A graph publish() creates or updates a Scriptable Graph; schematify push remains a normal document save and cannot replace one. Use schematify dry-run to run the same script without server writes.

Scripts run in the CLI’s bundled sandbox with a memory limit. Use --memory <mb> to raise that limit for larger scripts.

Publishing

Publish real-time channel values to nodes in schemas you own:

schematify publish updates.json                              # from file
echo '{"schemaId":"abc","patches":[...]}' | schematify pub - # from stdin
schematify publish -s <uuid> -n root/node status=active      # inline mode

See schematify publish --help for the full set of options.

Converting

Convert interchange format JSON into a valid Schematify document:

schematify convert interchange.json                     # convert from file
cat interchange.json | schematify convert -             # from stdin
schematify convert interchange.json --id my-diagram     # set document ID
schematify convert interchange.json --label "My Arch"   # set document label

Useful when working with AI agents that produce interchange format output.

Configuration

Manage your CLI configuration:

schematify config show     # display current settings
schematify config path     # show config file location
schematify config reset    # reset all configuration and credentials

If no config file exists, the CLI falls back to the hosted Schematify defaults. Use schematify config show to confirm which host and organisation the CLI is using, and use schematify setup to override those defaults for a custom VM.

Shell completions

Generate completion scripts for your shell:

schematify completion bash >> ~/.bashrc
schematify completion zsh >> ~/.zshrc
schematify completion fish > ~/.config/fish/completions/schematify.fish

Global flags

Flag	Purpose
--json	Structured JSON output (for scripting and piping)
--verbose	Verbose output
--debug	Debug output with full API request/response details
-q, --quiet	Suppress non-essential output

What’s next

• Scriptable Graphs: generate and update graphs from TypeScript.
• AI Integration: how AI agents work with Schematify.
• Agent Skills: skill files for creating and managing graphs with an agent.