# โšก Sesi Command Line Interface Reference Sesiโ€™s CLI is a powerful, zero-footprint environment orchestrator. It allows you to run robust scripts, evaluate inline code filelessly, query the RAG-powered interactive Sesira assistant, encrypt files, and manage sandboxing controls directly from your shell. --- ## ๐Ÿ—บ๏ธ CLI Command Reference Matrix | Command Syntax | Execution Mode | File Dependency | Description | | :------------------------------------- | :--------------------- | :-------------------------------- | :---------------------------------------------------------------------------------- | | `sesi ` | **Standard Execution** | Yes | Runs the Sesi script file to standard output stream. | | `sesi ` | **Parametric Script** | Yes | Runs the script and exposes trailing parameters in `args`. | | `sesi -e ""` | Inline Eval | **No (Fileless)** | Evaluates the string of Sesi code directly in-memory. | | `sesi -e "" ` | **Parametric Eval** | **No (Fileless)** | Evaluates inline code and populates `args` array with inputs. | | `sesi -h ""` | Sesira Help | **Yes (Internal chatbot script)** | Converses with Sesi's internal Vector-RAG chatbot (`chatbot/sesi_db_chatbot.sesi`). | | `sesi -h ""` | Grounded Help | **Yes (Chatbot + context file)** | Converses with Sesira using both the vector DB and the user's file. | | `sesi chatbot/sesira.sesi ""` | Direct Sesira | Yes | Runs the bundled chatbot directly with raw terminal output. | | `sesi -r ` | AST Dump | Yes | Dumps raw syntax JSON AST payload without running code. | | `sesi --ast ` | AST Visualization | Yes | Prints a pretty-printed, indented hierarchical tree representation of the AST. | | `sesi --tokens ` | Token Stream | Yes | Prints a structured, tabular grid detailing all tokens scanned by the Lexer. | | `sesi --repl` | Interactive REPL | **No (Interactive)** | Starts a live Sesi prompt session with auto-printing of evaluated expressions. | | `sesi -enc -p ` | Encryption | Yes | Secures a script file using AES-256 password protection. | | `sesi -c ` | Dry Run | Yes | Checks syntax, compilation, undefined symbols, and unused locals without executing. | | `sesi -dec -p ` | Decryption | Yes | Decrypts an encrypted script file back to cleartext `.sesi`. | | `sesi --timeout ` | Timed Run | Yes | Aborts execution after the given millisecond deadline. | | `sesi --profile ` | Profiled Run | Yes | Prints runtime performance measurements after execution. | --- ## ๐Ÿš€ 1. Parametric Script Execution You can feed command-line arguments to Sesi scripts on launch. Sesi parses these inputs and binds them as standard string values in a globally accessible array called `args`. ### Usage ```bash sesi main/test_args.sesi "hello" "world" ``` ### Accessing Arguments in Sesi Scripts ```sesi // Get the number of inputs let total = len(args) // Access indices if total > 0 { show "First argument:" args[0] } ``` --- ## ๐Ÿ”ฎ 2. Fileless Inline Execution (`-e` / `--eval`) You do not need to create or save `.sesi` files on your disk to use Sesi. Using the `-e` flag, you can execute logic on the fly. ### A. Statement Termination Rules Sesi requires statements to be terminated by either a **newline** or a **semicolon (`;`)**. #### Single-line Semicolon Pattern If writing on a single terminal line, separate statements manually with `;`: ```bash sesi -e "let x = 10; let y = 20; show x + y" ``` #### Multiline Shell Pattern If writing a multiline string in your shell, omit semicolons completely: ```bash sesi -e " let x = 10 let y = 20 show x + y " ``` ### B. Parametric Fileless Execution You can pass CLI arguments to fileless inline scripts too! Any positional arguments coming after the inline code string are loaded into the global `args` array. #### Example: Dynamic File Character Counter ```bash sesi -e "let path = args[0]; let content = read_file(path); show 'Character count:' len(content)" "package.json" ``` --- ## ๐ŸŽ“ 3. Interactive Sesira Help (`-h` / `--help`) Sesiโ€™s CLI features Sesira, an inline dynamic RAG (Retrieval-Augmented Generation) assistant trained directly on Sesi's grammar rules, standard library, and architecture documentation. ### A. General Knowledge Queries (Fileless) Ask Sesi how to write loops, parse JSON, what functions are available, what are the best practices in Sesi, etc: ```bash sesi -h "how do I use standard json module?" ``` ### B. Context-Grounded Code Debugging Pass a script file along with `-h` to chat with Sesira about your code. Sesira will automatically ingest the file contents as grounding context: ```bash sesi examples/main/01_hello.sesi -h "how can i improve this script?" ``` ### C. Direct Chatbot Execution Run the bundled chatbot directly when you need to start a new chat without conversational history context (logs are archived to chatbot/archive/): ```bash sesi chatbot/sesi_db_chatbot.sesi new "how do I use memory?" ``` --- ## โš™๏ธ 4. Security & Sandbox Overrides Sesi runs in a safe-by-default, zero-trust sandbox. System shell commands (`exec`, `spawn`) are blocked by default. Use these CLI flags to configure safety parameters: ### A. Disable Sandboxing (`-l` / `--local`) Unlocks the execution of raw system commands and allows directory whitelist escapes: ```bash sesi main/script.sesi --local ``` ### B. Directory Whitelisting (`-a` / `--allowed-paths`) Adds custom directories to the safe path whitelist (Current Working Directory and Script Directory are whitelisted by default): ```bash sesi main/script.sesi -a "./data,./logs" ``` --- ## ๐Ÿ“ฆ 5. Systems Utilities ### B. AST Visualization (`--ast`) Renders a pretty-printed, indented hierarchical tree structure of the Abstract Syntax Tree (AST): ```bash sesi --ast examples/main/01_hello.sesi ``` ### C. Token Stream Visualization (`--tokens`) Outputs a structured, formatted table showing all lexical tokens scanned by the lexer, detailing their Line, Column, Type, and raw Lexeme value: ```bash sesi --tokens examples/main/01_hello.sesi ``` ### D. AES-256 Script Encryption (`-enc` & `-dec`) Secure your proprietary reasoning instructions or pipelines using password-based encryption: ```bash # Encrypt manually with password parameter sesi -enc my_private_script.sesi -p "my-super-secret-password" # Decrypt manually with password parameter sesi -dec my_private_script.sesi -p "my-super-secret-password" ``` #### ๐Ÿ”’ Zero-Configuration Environment Fallback (`SESI_PASSWORD`) To avoid exposing passwords in your shell's history, you can set the `SESI_PASSWORD` environment variable in your `.env` file (or your system's shell environment). When Sesi detects `SESI_PASSWORD`, you can omit the `-p` parameter entirely: ```bash # Encrypt automatically using SESI_PASSWORD from env sesi -enc my_private_script.sesi # Decrypt automatically using SESI_PASSWORD from env sesi -dec my_private_script.sesi ``` ## ๐Ÿ’ฌ 6. Interactive REPL (`--repl` or no arguments) Sesi includes a full interactive Read-Eval-Print Loop (REPL). It keeps your variables and scopes persistent across statement entries. ### Usage Start the REPL in your shell: ```bash sesi --repl # or run `sesi` with no arguments in a terminal TTY sesi ``` Inside the REPL, any **Expression Statement** (like mathematical equations, string variables, or expressions) will auto-show its evaluated result to the terminal. ```sesi Sesi Interactive Terminal (v1.8.6) Type ".exit" or press ESC to exit. sesi> let x = 10 sesi> let y = 20 sesi> x + y 30 sesi> .exit ``` --- ## ๐Ÿ“ฅ 7. Interactive Console Input (`input`) Sesi scripts can pause execution and prompt the user for interactive console inputs step-by-step using the built-in `input()` function. ### Example ```sesi let name = input("What is your name? ") let age = input("What is your age? ") show "User info:" name "is" age "years old" ``` When executing this script in the terminal, Sesi will show the prompts sequentially, waiting for you to type your response and press **Enter** before proceeding to the next statement. --- ## ๐Ÿ› ๏ธ 8. Package.json Script Shortcuts If you are working inside the Sesi repository, you can leverage native package manager shortcuts defined in `package.json` to execute, parse, or encrypt scripts: | Package Script | CLI Equivalence | Description | | :---------------------------------- | :------------------------ | :---------------------------------------------------- | | `npm run lint` | `sesi lint.sesi` | Audits the entire workspace for errors/warnings. | | `npm run lint ` | `sesi lint.sesi ` | Audits a single file and prints directly to terminal. | | `npm run sesi ` | `sesi ` | Runs the Sesi script. | | `npm run sesi:local ` | `sesi -l ` | Runs a script with safe-mode disabled. | | `npm run sesi:dry ` | `sesi -c ` | Runs a dry run of the script. | | `npm run sesi:eval ""` | `sesi -e ""` | Evaluates Sesi code in-memory. | | `npm run sesi:parse ` | `sesi -r ` | Dumps the raw AST representation. | | `npm run sesi:encrypt ` | `sesi -enc ` | Encrypts a file (using env password fallback). | | `npm run sesi:decrypt ` | `sesi -dec ` | Decrypts a file (using env password fallback). | | `npm run repl` | `sesi --repl` | Starts the interactive Sesi REPL. | | `npm run sesira ""` | `sesi -h ""` | Consults the RAG-trained Sesira assistant. | | `npm run example:all` | `sesi examples.sesi` | Runs all examples in the examples/ directory. | ### Usage Example ```bash # Audit the entire workspace and save report to lint_report.md npm run lint # Audit a single file and show Errors & Warnings directly to stdout npm run lint bad-syntax-file.sesi # Evaluate inline code npm run sesi:eval "show 'Sesi running via npm!'" # Encrypt a private script using the .env password npm run sesi:encrypt "my-pipeline.sesi" ```