Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI Command Reference

Usage

juglans [OPTIONS] <FILE> [ARGS]
juglans <COMMAND> [OPTIONS]

Global Options:

OptionDescription
--input <JSON>Input data (JSON format)
--input-file <FILE>Read input from file
--verbose, -vVerbose output
--dry-runParse only, do not execute
--output <FILE>Write result to file
--output-format <FMT>Output format: text (default), json, sse
--chat-id <ID>Chat session ID for multi-turn conversation
--infoShow prompt info without executing

Command Summary

CommandDescription
juglans <file>Execute .jg / .jgx file
juglans initCreate a new project scaffold
juglans installInstall package dependencies from jgpackage.toml
juglans checkValidate file syntax
juglans whoamiShow account and config info
juglans serveStart unified server (HTTP API + every configured channel)
juglans chatLaunch interactive chat TUI
juglans testRun tests (test_* nodes in .jg files)
juglans doctestValidate code snippets in markdown docs
juglans packPack a package into .tar.gz
juglans publishPublish a package to the registry
juglans addAdd a package dependency
juglans removeRemove a package dependency
juglans deployDeploy project to Docker container
juglans cronRun a workflow on a cron schedule
juglans lspStart Language Server Protocol server
juglans skillsManage agent skills from GitHub

Execute File

Run a workflow or prompt file.

juglans <FILE> [OPTIONS]

File type is determined by extension:

ExtensionBehavior
.jgExecute workflow DAG
.jgxRender prompt template

Examples:

# Execute a workflow
juglans src/main.jg

# Pass JSON input
juglans src/main.jg --input '{"query": "Hello"}'

# Read input from file
juglans src/main.jg --input-file input.json

# Dry run (parse only)
juglans src/main.jg --dry-run

# JSON output for programmatic use
juglans src/main.jg --output-format json

# Render a prompt template
juglans src/prompts/greeting.jgx --input '{"name": "Alice"}'

init

Create a new project scaffold.

juglans init <PROJECT_NAME>

Example:

juglans init my-project

Generated structure:

my-project/
├── juglans.toml
└── src/
    ├── example.jg
    ├── workflows/
    ├── agents/
    ├── prompts/
    └── tools/

install

Install package dependencies from jgpackage.toml.

juglans install

Example:

juglans install

check

Validate syntax of .jg and .jgx files.

juglans check [PATH] [OPTIONS]
OptionDefaultDescription
PATH.File or directory to check
--allShow warnings in addition to errors
--format <FMT>textOutput format: text, json

Exit codes: 0 = all valid, 1 = errors found.

Examples:

# Check all files in current directory
juglans check

# Check a specific file
juglans check workflow.jg

# Check a directory with warnings
juglans check ./src/ --all

# JSON output (for CI)
juglans check --format json

whoami

Show current account and configuration information.

juglans whoami [OPTIONS]
OptionDescription
--verbose, -vShow detailed info (resource paths, server config)

Examples:

juglans whoami
juglans whoami -v

serve

The single entry point that runs the HTTP API plus every channel configured under [channels.*] — Telegram bots (polling or webhook), WeChat accounts (auto-discovered), Discord gateways, Feishu event subscriptions, and Feishu incoming webhooks — in one process. Active channels (long-poll, websocket) get a tokio task each; passive channels (webhooks) mount their routes on the shared axum router.

juglans serve [OPTIONS]
OptionDefaultDescription
--port <PORT>, -p3000Port for the web server
--host <HOST>127.0.0.1Host address to bind
--entry <FILE>main.jgWorkflow entry file (defaults to main.jg in the project root)

HTTP endpoints (always mounted):

EndpointMethodDescription
/api/promptsGETList prompts
/api/workflowsGETList workflows (with validation)
/api/chatPOSTChat (SSE stream)
/api/chat/tool-resultPOSTReturn client tool result
/healthGETLiveness probe
/webhook/<kind>/<instance_id>POSTOne per passive-ingress channel (Feishu event, Telegram webhook), mounted by Channel::install_routes
(catch-all)*Fallback to serve() workflow when present

Port resolution: --port flag > [server] port in juglans.toml > 8080 (only when no juglans.toml exists at all). Project scaffolds ship with port = 3000, which is why local dev typically shows 3000.

Examples:

juglans serve
juglans serve --port 8080 --host 0.0.0.0
juglans serve --entry src/api.jg

A single channel failure (token expired, network down) is logged and that task exits — other channels keep running. Per-channel agent lets different bots route to different workflows; the orchestrator caches one dispatcher per unique agent slug. See [channels.*] for instance-level config.


Removed subcommands

  • juglans web — the dev-only HTTP server is gone; juglans serve is the single entry point. Old configs work unchanged: [server] port = 3000 continues to apply, the same /api/* endpoints are mounted, and (if no [channels.*] is configured) no channels boot, matching the old web behavior. Just substitute the command.
  • juglans bot <platform> — removed in favor of juglans serve. Migrate [bot.telegram] / [bot.feishu] / [bot.wechat] / [bot.discord] config to [channels.<kind>.<id>] form (see config docs). The old subcommand exits with an error message pointing here.

chat

Launch interactive chat TUI.

juglans chat [OPTIONS]
OptionDescription
--agent <FILE>, -aPath to an agent file (e.g. ./agents/assistant.jg)

Example:

juglans chat --agent ./agents/assistant.jg

test

Discover and execute test_* nodes in .jg files.

juglans test [PATH] [OPTIONS]
OptionDefaultDescription
PATH./tests/File or directory to test
--filter <NAME>Filter tests by name substring
--format <FMT>textOutput format: text, json, junit

Examples:

juglans test
juglans test ./tests/ --filter auth
juglans test --format junit

doctest

Validate ```juglans code blocks in markdown files through the parser.

juglans doctest [PATH] [OPTIONS]
OptionDefaultDescription
PATH./docs/File or directory
--format <FMT>textOutput format: text, json

Examples:

juglans doctest
juglans doctest docs/reference/workflow-spec.md
juglans doctest --format json

skills

Manage Agent Skills — packaged capabilities (workflows + prompts + tools) fetched from a GitHub repository and converted to .jgx templates.

juglans skills <SUBCOMMAND>

skills add

Fetch one or more skills from a GitHub repo and save them as .jgx files under ./prompts/ (or a custom output directory).

juglans skills add <REPO> [OPTIONS]
OptionDescription
REPOGitHub repo in owner/repo form, e.g. anthropics/skills
--skill <NAME>Specific skill to fetch (repeatable)
--allFetch every skill discovered in the repo
--listOnly list available skill names, don’t download
--output <DIR>, -oOutput directory (default: ./prompts)

skills list / skills remove

juglans skills list                    # list locally-installed skills
juglans skills remove <NAME>           # delete one

Examples:

juglans skills add anthropics/skills --list
juglans skills add anthropics/skills --skill pdf
juglans skills add anthropics/skills --all -o ./my-prompts
juglans skills list
juglans skills remove pdf

pack

Pack a package directory into a .tar.gz archive.

juglans pack [PATH] [OPTIONS]
OptionDescription
PATHPackage directory (default: .)
--output <DIR>, -oOutput directory

Example:

juglans pack ./my-package -o ./dist

publish

Publish a package to the registry.

juglans publish [PATH]
OptionDescription
PATHPackage directory (default: .)

Example:

juglans publish

add / remove

Manage package dependencies.

juglans add <PACKAGE>
juglans remove <PACKAGE>

Package format: name or name@version (e.g., sqlite-tools@^1.2.0).

Examples:

juglans add sqlite-tools
juglans add sqlite-tools@^1.2.0
juglans remove sqlite-tools

deploy

Deploy project to a Docker container.

juglans deploy [PATH] [OPTIONS]

Arguments:

NameDescription
PATHProject directory (default: current directory)

Options:

OptionDescription
--tag <TAG>Custom image tag (default: juglans-{project}:latest)
--port <PORT>, -pHost port (default: 8080)
--build-onlyBuild image without starting container
--pushPush image to registry after build
--stopStop and remove running container
--statusShow container status
--env <KEY=VAL>, -eEnvironment variables (repeatable)

Examples:

juglans deploy
juglans deploy --port 3000 -e API_KEY=xxx
juglans deploy --build-only --push
juglans deploy --stop
juglans deploy --status

cron

Run a workflow on a cron schedule (local dev scheduler).

juglans cron <FILE> [OPTIONS]
OptionDescription
--schedule <EXPR>, -sCron expression (required for .jg files; overrides manifest metadata for .jgflow)

Example:

juglans cron src/daily-report.jg -s "0 9 * * *"
juglans cron my-package.jgflow                # uses `schedule` from the manifest

.jg files have no schedule metadata, so --schedule is required. .jgflow package manifests may embed the schedule.


lsp

Start the Language Server Protocol server for editor integration.

juglans lsp

Exit Codes

CodeDescription
0Success
1General error
2Parse error
3Execution error
4Configuration error
5Network error