[CLI Guide]

CLI Guide

Abstract

The pynescript console script is a thin Click group over the same helpers used by the library API. It is optimized for shell pipelines, CI gates, and one-shot inspection — not for multi-bar evaluation (use the library Runtime or Pro API for that). This guide covers workflows; exhaustive flags are in CLI commands.

Conceptual model

Commands mirror pynescript.ast.helper and friends:

Interface surface

pynescript --help
pynescript --version
pynescript <command> --help

Not part of this Click group: starting the language server — use pynescript-lsp.

Internals (repo paths)

Invariants & edge cases

• Encoding default is UTF-8 for file reads/writes.
• --output-file - means stdout (Click allow_dash=True).
• Lint without a path reads stdin — useful in git hooks and cat script.pine | pynescript lint.
• --fail-on defaults to errors (syntax/E001); warnings fails on any warning severity too; all fails if any issue exists.
• data default provider is mock — offline-safe.
• Alpha Vantage without key prints a warning and uses demo.
• Download command requires an explicit directory; create parents as needed (implementation writes into the given path).

Worked examples

Inspect structure of a strategy

pynescript parse-and-dump examples/rsi_strategy.pine --indent 2 | less

Compare two scripts’ shapes in CI:

pynescript parse-and-dump a.pine --output-file /tmp/a.ast
pynescript parse-and-dump b.pine --output-file /tmp/b.ast
diff -u /tmp/a.ast /tmp/b.ast

Format / normalize

pynescript parse-and-unparse messy.pine --output-file clean.pine
# in-place-ish via shell:
pynescript parse-and-unparse strategy.pine --output-file strategy.pine.tmp \
  && mv strategy.pine.tmp strategy.pine

Lint gate in CI

set -e
pynescript lint strategies/ --help  # note: single file PATH, not directory recursion
# {/* TODO: verify multi-file; current CLI is one file or stdin */}
for f in strategies/*.pine; do
  pynescript lint --fail-on warnings "$f"
done

Stdin pipeline:

git show HEAD:strategies/rsi.pine | pynescript lint --fail-on errors -

Market data smoke checks

pynescript data AAPL
pynescript data AAPL --provider yahoo --period 1y --interval 1d
pynescript data BTC/USDT --provider ccxt --exchange binance
pynescript data EUR/USD --provider alphavantage --api-key "$AV_KEY"

Typical stdout shape (fields from __main__.py):

Symbol: AAPL
Bars: N
Date range: N bars
First close: ...
Last close: ...
Volume (avg): ...

Refresh builtin corpus (contributors / offline tests)

pynescript download-builtin-scripts --script-dir tests/data/builtin_scripts

Use sparingly: network + rate limits; CI may cache the corpus.

Compose with library for evaluation

CLI stops at parse/lint/data. Chain:

# normalize then evaluate in Python
pynescript parse-and-unparse strat.pine --output-file /tmp/s.pine
python - <<'PY'
from pathlib import Path
from pynescript.ast.helper import parse
# hand off to Runtime or your own visitor
print(parse(Path("/tmp/s.pine").read_text()).__class__.__name__)
PY

Failure modes

See also

• CLI commands reference
• Library API
• Quick start
• Troubleshooting