CLI Command Reference
Usage
juglans [OPTIONS] <FILE> [ARGS]
juglans <COMMAND> [OPTIONS]
Global Options:
| Option | Description |
|---|---|
--input <JSON> | Input data (JSON format) |
--input-file <FILE> | Read input from file |
--verbose, -v | Verbose output |
--dry-run | Parse 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 |
--info | Show prompt info without executing |
Command Summary
| Command | Description |
|---|---|
juglans <file> | Execute .jg / .jgx file |
juglans init | Create a new project scaffold |
juglans install | Install package dependencies from jgpackage.toml |
juglans check | Validate file syntax |
juglans whoami | Show account and config info |
juglans serve | Start unified server (HTTP API + every configured channel) |
juglans chat | Launch interactive chat TUI |
juglans test | Run tests (test_* nodes in .jg files) |
juglans doctest | Validate code snippets in markdown docs |
juglans pack | Pack a package into .tar.gz |
juglans publish | Publish a package to the registry |
juglans add | Add a package dependency |
juglans remove | Remove a package dependency |
juglans deploy | Deploy project to Docker container |
juglans cron | Run a workflow on a cron schedule |
juglans lsp | Start Language Server Protocol server |
juglans skills | Manage agent skills from GitHub |
Execute File
Run a workflow or prompt file.
juglans <FILE> [OPTIONS]
File type is determined by extension:
| Extension | Behavior |
|---|---|
.jg | Execute workflow DAG |
.jgx | Render 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]
| Option | Default | Description |
|---|---|---|
PATH | . | File or directory to check |
--all | Show warnings in addition to errors | |
--format <FMT> | text | Output 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]
| Option | Description |
|---|---|
--verbose, -v | Show 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]
| Option | Default | Description |
|---|---|---|
--port <PORT>, -p | 3000 | Port for the web server |
--host <HOST> | 127.0.0.1 | Host address to bind |
--entry <FILE> | main.jg | Workflow entry file (defaults to main.jg in the project root) |
HTTP endpoints (always mounted):
| Endpoint | Method | Description |
|---|---|---|
/api/prompts | GET | List prompts |
/api/workflows | GET | List workflows (with validation) |
/api/chat | POST | Chat (SSE stream) |
/api/chat/tool-result | POST | Return client tool result |
/health | GET | Liveness probe |
/webhook/<kind>/<instance_id> | POST | One 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 serveis the single entry point. Old configs work unchanged:[server] port = 3000continues to apply, the same/api/*endpoints are mounted, and (if no[channels.*]is configured) no channels boot, matching the oldwebbehavior. Just substitute the command.juglans bot <platform>— removed in favor ofjuglans 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]
| Option | Description |
|---|---|
--agent <FILE>, -a | Path 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]
| Option | Default | Description |
|---|---|---|
PATH | ./tests/ | File or directory to test |
--filter <NAME> | Filter tests by name substring | |
--format <FMT> | text | Output 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]
| Option | Default | Description |
|---|---|---|
PATH | ./docs/ | File or directory |
--format <FMT> | text | Output 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]
| Option | Description |
|---|---|
REPO | GitHub repo in owner/repo form, e.g. anthropics/skills |
--skill <NAME> | Specific skill to fetch (repeatable) |
--all | Fetch every skill discovered in the repo |
--list | Only list available skill names, don’t download |
--output <DIR>, -o | Output 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]
| Option | Description |
|---|---|
PATH | Package directory (default: .) |
--output <DIR>, -o | Output directory |
Example:
juglans pack ./my-package -o ./dist
publish
Publish a package to the registry.
juglans publish [PATH]
| Option | Description |
|---|---|
PATH | Package 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:
| Name | Description |
|---|---|
PATH | Project directory (default: current directory) |
Options:
| Option | Description |
|---|---|
--tag <TAG> | Custom image tag (default: juglans-{project}:latest) |
--port <PORT>, -p | Host port (default: 8080) |
--build-only | Build image without starting container |
--push | Push image to registry after build |
--stop | Stop and remove running container |
--status | Show container status |
--env <KEY=VAL>, -e | Environment 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]
| Option | Description |
|---|---|
--schedule <EXPR>, -s | Cron 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
.jgfiles have no schedule metadata, so--scheduleis required..jgflowpackage manifests may embed the schedule.
lsp
Start the Language Server Protocol server for editor integration.
juglans lsp
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Parse error |
| 3 | Execution error |
| 4 | Configuration error |
| 5 | Network error |