tools/script.html

---
active_crumb: Command Line
layout: documentation
fa_icon: fa-tools
id: script
---

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<div class="col-md-8 second-column">
    <section id="tldr">
        <h2 class="section-title">TL;DR; <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            Watch this quick video (12:05) for introduction to NLPCraft CLI:
        </p>
        <div>
            <iframe
                    width="514"
                    height="289"
                    src="https://www.youtube.com/embed/LNfny60bmgg?modestbranding=1"
                    title="NLPCraft - Command Line Utility"
                    frameborder="0"
                    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
                    allowfullscreen>
            </iframe>
        </div>
    </section>
    <section id="overview">
        <h2 class="section-title">Overview <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            NLPCraft CLI <code>bin/nlpcraft.{sh|cmd}</code> script is a <b>central management utility</b> for NLPCraft that supports
            interactive REPL and command line modes. Most of the functions this script does can be done through running
            Java applications or using REST API - yet using this script you can perform the same tasks much simpler and quicker.
            From starting and managing REST server and probes, running various built-in tools, to testing models via REST API -
            NLPCraft CLI provides a single centralized utility that makes a quick work out
            of all these routine tasks.
        </p>
        <p>
            The script is only available in either official Apache <a href="/download.html#src">source ZIP</a> or in
            <a href="/download.html#zip">binary ZIP</a> distributions. If you used Maven or similar build tools to
            add NLPCraft to your project as a dependency, this script will not be available out-of-the-box - you will
            need to download ZIP distribution separately.
        </p>
        <div class="bq warn">
            <b>ZIP Distribution</b>
            <p>
                The NLPCraft CLI is only available in <a href="/download.html">ZIP distributions</a>. For Maven/Gradle/SBT
                projects you will need to download <a href="/download.html">ZIP distribution</a> separately.
            </p>
        </div>
        <p>
            The script is located in <code>/bin</code> sub-folder of the installation root and is available as
            <code>nlpcraft.sh</code> for <i class="fab fa-fw fa-linux"></i> and <code>nlpcraft.cmd</code>
            for <i class="fab fa-fw fa-windows"></i> environments. Both versions provide identical functionality.
        </p>
    </section>
    <section id="quick_start">
        <h2 class="section-title">Quick Start <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            The <code>bin/nlpcraft.{sh|cmd}</code> works in two modes:
        </p>
        <ul>
            <li>
                Command line mode where it executes a single command at a time.
            </li>
            <li>
                Interactive REPL mode. To enter REPL mode run <code>bin/nlpcraft.{sh|cmd}</code> without arguments.
            </li>
        </ul>
        <p>
            All the functionality and command syntax remain the same regardless of whether a command is executed from a command line or
            in REPL mode.
        </p>
        <p>
            To get started, run <code>bin/nlpcraft.{sh|cmd}</code>:
        </p>
        <p>
            <img class="img-fluid" src="/images/cli1.png" alt="">
        </p>
        <p>
            Script starts in the REPL mode by default.
        </p>
        <div class="bq info">
            <b>REPL Prompt</b>
            <p>
                REPL prompt shows 4 pieces of information:
            </p>
            <ul>
                <li>REST server status (<code>ON</code> if server is started and detected, <code>OFF</code> otherwise).</li>
                <li>Local probe status (<code>ON</code> if probe is started and connected to the server, <code>OFF</code> otherwise).</li>
                <li>REST access token if the user is signed in. This token is required for all REST calls.</li>
                <li>Current user working directory.</li>
            </ul>
            <p>
                Note that when using <code>start-server</code> command the <a href="/using-rest.html#users">default user account</a> is automatically signed in
                upon the server start and the access token is obtained. You can sign in with different user account, if necessary.
            </p>
        </div>
        <h2 class="section-sub-title">Get Command List <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            Type <code>help</code> to list all supported commands (or run <code>bin/nlpcraft.{sh|cmd} help</code> if in command line mode):
        </p>
        <p>
            <img class="img-fluid" src="/images/cli2.png" alt="">
        </p>
        <p>
            You can get detailed instructions and usage examples for any command
            <code>xxx</code> by typing <code>help --cmd=xxx</code>, for example:
        </p>
        <p>
            <img style="max-width: 914px !important;" class="img-fluid" alt="" src="/images/cli7.png">
        </p>
        <p>
            Use <span class="keyboard">Tab</span> key anytime for auto-completion for commands, parameters, file system paths, and model class names.
            Use <span class="keyboard">↑</span> and <span class="keyboard">↓</span> keys to scroll through command history.
        </p>
        <p>
            To exit <code>bin/nlpcraft.{sh|cmd}</code> script in REPL mode use <code>quit</code> command.
        </p>
    </section>
    <section id="os_commands">
        <h2 class="section-title">OS Commands <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            You can run any external OS-specific commands from <code>bin/nlpcraft.{sh|cmd}</code> script by prepending such
            command with a <code>$</code> symbol. For example:
        </p>
        <pre class="brush: bash">
            > $git pull # Runs 'git pull' in the current directory.
            > $vi /home/myproject/pom.xml # Edit 'pom.xml' using vi.
            > $emacs /home/myproject/MyModel.scala # Edit 'MyModel.scala' using emacs.
            > $ls -la # Run 'ls-la' Unix command.
            > $cmd /c dir # Runs Windows 'dir' command in a separate shell.
        </pre>
        <p>
            Note that <em>stdin</em>, <em>stderr</em> and <em>stdout</em> of the new process will inherit from running <code>bin/nlpcraft.{sh|cmd}</code> script process.
            Running OS commands makes the most sense in REPL mode where you don't want to lose a session context while
            executing external OS commands. Technically, however, external OS commands can be executed from command line mode
            as well.
        </p>
    </section>
    <section id="tips">
        <h2 class="section-title">Tips <span class="amp">&amp;</span> Tricks <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            NLPCraft CLI is standard command line utility that can be used in the familiar ways both in
            Linux/Unix/MacOS and Window environments.
        </p>
        <span class="section-sub-title">Typical Development Workflow <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></span>
        <p>
            Here's the typical workflow of working with NLPCraft using NLPCraft CLI. Note that although all of these
            steps can be performed from IDE or a command line - NLPCraft CLI in REPL model provides the easiest
            way to accomplish these tasks:
        </p>
        <ol>
            <li>
                <code>gen-project</code> command generates new Maven/Gradle/Sbt project for either Java, Scala, Groovy
                or Kotlin that is ready to run.
            </li>
            <li>
                <code>start-server</code> command starts the local REST server. You only need to do it once as it is a
                "fire and forget" component.
            </li>
            <li>
                Modify <span class="amp">&amp;</span> build the project using IDE or editor of your choice. You can
                <a href="#os_commands">launch</a> the editor and build tooling right from NLPCraft CLI.
            </li>
            <li>
                <code>test-model</code> command runs auto-validator for your model automatically starting and stopping an
                embedded data probe. Alternatively, <code>start-probe</code> and <code>ask</code> commands allow to manually
                start the local data probe and issue REST requests.
                <ul>
                    <li>
                        Note that you can use <code>retest-model</code> and <code>restart-probe</code> commands in REPL mode
                        to rerun the latest model test or restart the probe with the last set of parameters accordingly avoiding
                        the retyping of all required parameters.
                    </li>
                </ul>
            </li>
            <li>
                Repeat steps 3 and 4 as you develop, test and debug your models and applications.
            </li>
            <li>
                Once finished - <code>stop</code> command stops both local REST server and data probe. Note that stopping
                the server once again is an optional step as it is a "fire and forget" component and it can be reused between development
                sessions.
            </li>
        </ol>
        <div class="bq info">
            <p>
                Steps 3 and 4 define a typical development cycle for change, build and test. In most cases you <b>don't need</b>
                to restart the server between multiple sessions.
            </p>
        </div>
        <span class="section-sub-title">Using <code>start-server</code> Command <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></span>
        <p>
            REST server is a fire-and-forget component in NLPCraft. You can start it once and you only need to restart it
            if you change the server configuration. It is customary to add <code>bin/nlpcraft.{sh|cmd} start-server</code>
            call to the OS init script to have it started automatically on boot up.
        </p>
        <span class="section-sub-title">Using Default <code>nlpcraft.conf</code> <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></span>
        <p>
            It is recommended to modify the standard <code>nlpcraft.conf</code> configuration file, i.e. <em>in a standard
            installation location</em>. Commands like <code>start-server</code>, <code>start-probe</code> and
            <code>test-model</code> use this location by default and you will not have to specify alternative
            location or provide other overrides every time you run these commands.
            If you keep all your configuration modifications in the standard <code>nlpcraft.conf</code> file you can simply
            run these commands without any additional arguments - significantly simplifying their usage.
        </p>
        <span class="section-sub-title">Using NLPCraft CLI In Scripts <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></span>
        <p>
            NLPCraft CLI can be used in your own scripts to automate your own specific workflow and tasks.
            All of the commands that utilize REST API produce JSON responses, for a example:
        </p>
        <p>
            <img class="img-fluid" src="/images/cli9.png" alt="">
        </p>
        <p>
            You can parse these JSON responses for your own needs in your scripts. For example, here's the
            code snippet to get the access token from the <code>signin</code> command (on Linux):
        </p>
        <pre class="brush: bash">
            $ bin/nlpcraft.sh no-ansi no-logo signin --email=admin@admin.com --passwd=admin | tail -n +2 | jq -M '.acsTok' | tr -d '"'
        </pre>
        <p>
        ...and the access token is:
        </p>
        <pre class="brush: bash">
            bjok7yraypseyk86KgGae
        </pre>
        <p>
            <b>NOTES:</b>
        </p>
        <ul>
            <li>
                We use <code>no-ansi</code> and <code>no-logo</code> commands that clean up and simplify the
                output so that it would be easier to parse the resulting JSON.
            </li>
            <li>
                We use <code>tail -n +2</code> Unix command to skip the 1st line of the output that contains HTTP return code.
            </li>
            <li>
                We use <a target=_blank href="https://stedolan.github.io/jq/">jq</a> utility to parse JSON inline and extract
                <code>acsTok</code> field.
            </li>
            <li>
                We use <code>tr -d '"'</code> to remove surrounding double quotes to get our final result.
            </li>
        </ul>
    </section>
</div>
<div class="col-md-2 third-column">
    <ul class="side-nav">
        <li class="side-nav-title">On This Page</li>
        <li><a href="#overview">Overview</a></li>
        <li><a href="#quick_start">Quick Start</a></li>
        <li><a href="#os_commands">OS Commands</a></li>
        <li><a href="#tips">Tips <span class="amp">&amp;</span> Tricks</a></li>
        {% include quick-links.html %}
    </ul>
</div>