command-line-interface.ttl

@prefix ldh:    <https://w3id.org/atomgraph/linkeddatahub#> .
@prefix rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dh:     <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .

<> a dh:Item ;
    dct:title "Command line interface" ;
    dct:description "CLI scripts can be used perform all actions available in the UI" ;
    rdf:_1 <#content> .

<#content> a ldh:XHTML ;
    rdf:value """<div xmlns="http://www.w3.org/1999/xhtml">
    <p class="lead">CLI scripts can be used perform all actions available in the UI</p>
    <p>LinkedDataHub CLI wraps the <a href="../http-api/">HTTP API</a> into a set of shell scripts with convenient parameters. The scripts should run on any Unix-based system.
        They can be used for testing, automation, scheduled execution and such. It is usually much quicker to perform actions using CLI rather than the
        <a href="../user-interface/">user interface</a>, as well as easier to reproduce.</p>
    <p>Some scripts correspond to a single request to LinkedDataHub, others combine others into tasks with multiple interdependent requests, such as the CSV import.</p>
    <p>You will need to supply a <samp>.pem</samp> file of your <a href="../../get-started/#get-webid">WebID certificate</a> as well as its password as script arguments, among others.</p>
    <div class="alert alert-info">
        <p>The CLI scripts live in the <samp>bin</samp> folder and need to be added to the <code>$PATH</code> environmental variable. For example:</p>
        <pre>export PATH="$(find bin -type d -exec realpath {} \\; | tr '\n' ':')$PATH"</pre>
        <p>They also use the <a href="https://jena.apache.org/documentation/tools/" target="_blank">Jena's CLI commands</a> internally, so make sure to have them on <code>$PATH</code> before running the scripts.</p>
    </div>
    <div>
        <h2 id="parameters">Parameters</h2>
        <p>Common parameters used by most scripts include:</p>
        <dl>
            <dt>-f</dt>
            <dt>--cert-pem-file</dt>
            <dd><samp>.pem</samp> file with the WebID certificate of the agent</dd>
            <dt>-p</dt>
            <dt>--cert-password</dt>
            <dd>Password of the WebID certificate</dd>
            <dt>-b</dt>
            <dt>--base</dt>
            <dd>Base URI of the application</dd>
            <dt>--proxy</dt>
            <dd>The host this request will be proxied through (optional)</dd>
            <dd>It can be used with port 5443 for which the client certificate authentication is always enabled, for example <samp>--proxy https://localhost:5443/</samp></dd>
        </dl>
        <p>Other parameters are script-specific.</p>
    </div>
    <div>
        <h2 id="usage">Usage</h2>
        <p>A usage message with parameters of a script is printed when the scripted is run without any arguments. There can be named parameters and default parameters, both of those can be optional. For example:</p>
        <pre>$ add-select.sh
Creates a SPARQL SELECT query.

Usage:  add-select.sh options

Options:
  -f, --cert-pem-file CERT_FILE        .pem file with the WebID certificate of the agent
  -p, --cert-password CERT_PASSWORD    Password of the WebID certificate
  -b, --base BASE_URI                  Base URI of the application
  --proxy PROXY_URL                    The host this request will be proxied through (optional)

  --title TITLE                        Title of the chart
  --description DESCRIPTION            Description of the chart (optional)
  --uri URI                            URI of the query (optional)

  --query-file ABS_PATH                Absolute path to the text file with the SPARQL query string
  --service SERVICE_URI                URI of the SPARQL service specific to this query (optional)</pre>
        <p>The optional parameters are marked with <samp>(Optional)</samp>. In this case there is no default argument, but some scripts require document (named graph) URI as the default parameter, e.g. ontology document URL.</p>
        <p>This is how an <samp>add-select.sh</samp> invocation would look like:</p>
        <pre>add-select.sh \\
  -b "$base" \\
  -f ./ssl/owner/cert.pem \\
  -p "$owner_cert_password" \\
  --proxy "$proxy" \\
  --title "Select concepts" \\
  --query-file "$pwd/queries/select-concepts.rq"</pre>
    </div>
    <div>
        <h2 id="scripts">Scripts</h2>
        <p>Currently supported:</p>
        <table class="table table-striped">
            <thead>
                <tr>
                    <th>Purpose</th>
                    <th>Script</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <th colspan="2">Low-level (Graph Store Protocol)</th>
                </tr>
                <tr>
                    <td><samp>GET</samp> request</td>
                    <td><samp>get.sh</samp></td>
                </tr>
                <tr>
                    <td><samp>POST</samp> request</td>
                    <td><samp>post.sh</samp></td>
                </tr>
                <tr>
                    <td><samp>PUT</samp> request</td>
                    <td><samp>put.sh</samp></td>
                </tr>
                <tr>
                    <td><samp>PATCH</samp> request</td>
                    <td><samp>patch.sh</samp></td>
                </tr>
                <tr>
                    <td><samp>DELETE</samp> request</td>
                    <td><samp>delete.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2">Documents</th>
                </tr>
                <tr>
                    <td>Create container document</td>
                    <td><samp>create-container.sh</samp></td>
                </tr>
                <tr>
                    <td>Create item document</td>
                    <td><samp>create-item.sh</samp></td>
                </tr>
            </tbody>

            <tbody>
                <tr>
                    <th colspan="2">Content</th>
                </tr>
                <tr>
                    <td>Append object block (instance of <samp>ldh:Object</samp>) to document</td>
                    <td><samp>content/add-object-block.sh</samp></td>
                </tr>
                <tr>
                    <td>Append XHTML block (instance of <samp>ldh:XHTML</samp>) to document</td>
                    <td><samp>content/add-xhtml-block.sh</samp></td>
                </tr>
                <tr>
                    <td>Remove block from document</td>
                    <td><samp>content/remove-block.sh</samp></td>
                </tr>
            </tbody>

            <tbody>
                <tr>
                    <th colspan="2">Instances of system classes</th>
                </tr>
                <tr>
                    <td>Append service (instance of <samp>ldh:GenericService</samp>) to document</td>
                    <td><samp>add-generic-service.sh</samp></td>
                </tr>
                <tr>
                    <td>Append result set chart (instance of <samp>ldh:ResultSetChart</samp>) to document</td>
                    <td><samp>add-result-set-chart.sh</samp></td>
                </tr>
                <tr>
                    <td>Append <code>SELECT</code> query (instance of <samp>sp:Select</samp>) to document</td>
                    <td><samp>add-select.sh</samp></td>
                </tr>
                <tr>
                    <td>Append SPARQL view (instance of <samp>ldh:View</samp>) to document</td>
                    <td><samp>add-view.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2"><a href="../imports/">Imports</a></th>
                </tr>
                <tr>
                    <td>Create file</td>
                    <td><samp>add-file.sh</samp></td>
                </tr>
                <tr>
                    <td>Create CONSTRUCT query</td>
                    <td><samp>add-construct.sh</samp></td>
                </tr>
                <tr>
                    <td>Create CSV import</td>
                    <td><samp>imports/add-csv-import.sh</samp></td>
                </tr>
                <tr>
                    <td>Import CSV data</td>
                    <td><samp>imports/import-csv.sh</samp></td>
                </tr>
                <tr>
                    <td>Create RDF import</td>
                    <td><samp>imports/add-rdf-import.sh</samp></td>
                </tr>
                <tr>
                    <td>Import RDF data</td>
                    <td><samp>imports/import-rdf.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2"><a href="../administration/">Administration</a></th>
                </tr>
                <tr>
                    <td>Add <code>owl:import</code> to ontology</td>
                    <td><samp>admin/add-ontology-import.sh</samp></td>
                </tr>
                <tr>
                    <td>Clear and reload ontology</td>
                    <td><samp>admin/clear-ontology.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2"><a href="../administration/acl/">Access control</a></th>
                </tr>
                <tr>
                    <td>Add <a href="../administration/acl/#agents">agent</a> to <a href="../administration/acl/#groups">group</a></td>
                    <td><samp>admin/acl/add-agent-to-group.sh</samp></td>
                </tr>
                <tr>
                    <td>Create <a href="../administration/acl/#authorizations">authorization</a></td>
                    <td><samp>admin/acl/create-authorization.sh</samp></td>
                </tr>
                <tr>
                    <td>Create <a href="../administration/acl/#groups">group</a></td>
                    <td><samp>admin/acl/create-group.sh</samp></td>
                </tr>
                <tr>
                    <td>Make application publicly readable to any agent</td>
                    <td><samp>admin/acl/make-public.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2"><a href="../administration/ontologies/">Ontologies</a></th>
                </tr>
                <tr>
                    <td>Add <a href="../administration/ontologies/#classes">class</a></td>
                    <td><samp>admin/ontologies/add-class.sh</samp></td>
                </tr>
                <tr>
                    <td>Add <code>CONSTRUCT</code> query</td>
                    <td><samp>admin/ontologies/add-constructor.sh</samp></td>
                </tr>
                <tr>
                    <td>Create <a href="../administration/ontologies/#ontologies">ontology</a></td>
                    <td><samp>admin/ontologies/create-ontology.sh</samp></td>
                </tr>
                <tr>
                    <td>Add <a href="../administration/ontologies/#constraints">property constraint</a></td>
                    <td><samp>admin/ontologies/add-property-constraint.sh</samp></td>
                </tr>
                <tr>
                    <td>Add restriction</td>
                    <td><samp>admin/ontologies/add-restriction.sh</samp></td>
                </tr>
                <tr>
                    <td>Add <code>SELECT</code> query</td>
                    <td><samp>admin/ontologies/add-select.sh</samp></td>
                </tr>
                <tr>
                    <td>Import ontology</td>
                    <td><samp>admin/ontologies/import-ontology.sh</samp></td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <th colspan="2"><a href="../administration/packages/">Packages</a></th>
                </tr>
                <tr>
                    <td>Install package</td>
                    <td><samp>admin/packages/install-package.sh</samp></td>
                </tr>
                <tr>
                    <td>Uninstall package</td>
                    <td><samp>admin/packages/uninstall-package.sh</samp></td>
                </tr>
            </tbody>
        </table>
        <p>Usage example:</p>
        <pre>add-file.sh \\
  -b "https://localhost:4443/" \\
  -f ./ssl/owner/cert.pem \\
  -p "$owner_cert_password" \\
  --title "Friends" \\
  --file friends.csv \\
  --content-type text/csv</pre>
        <p>See also the <a href="../../user-guide/import-data/">data import user guides</a>.</p>
    </div>
    <p class="lead">Find the <a href="https://github.com/AtomGraph/LinkedDataHub/tree/master/bin" target="_blank">CLI scripts on GitHub</a> or check out the
        <a href="https://github.com/AtomGraph/LinkedDataHub-Apps/tree/master/demo" target="_blank">demo apps</a> that use them.</p>
</div>"""^^rdf:XMLLiteral .