Added information about the CLI Query interface, and http with curl

Author: hoijnet

src/app/docs/http-documents-api/page.md

@@ -0,0 +1,112 @@
+---
+title: How to use the HTTP Documents API
+nextjs:
+  metadata:
+    title: How to use the HTTP Documents API
+    description: Quick introduction to the HTTP Documents API and how to use common ways to interact with it using various clients as a quick reference guide
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/http-documents-api/
+media: []
+---
+
+TerminusDB exposes a REST API for documents, a WOQL query interface with a datalog interface to the database and a GraphQL API, and several endpoints described in the [TerminusDB OpenAPI specification](/docs/openapi/).
+
+The purpose of this guide is to show how to connect with both cloud and local TerminusDB instances. This is a simple way to interact with the database, without using the client libraries.
+
+There are two main ways to authenticate with TerminusDB:
+
+1. API token (for cloud instances)
+2. Basic authentication (when connecting to a local TerminusDB instance, such as in [Docker](/docs/install-terminusdb-as-a-docker-container/))
+
+## Localhost TerminusDB
+
+Here is a tutorial to connect to TerminusDB in docker or on localhost.
+
+### Updating a document on localhost
+
+* Instance name: admin
+* Data Product name: PeopleReferenceData
+* Graph: schema
+* Branch name: main
+* Schema document: Role
+* User: admin
+* Password: password
+* Provider: localhost:6363
+
+```bash
+BASE64="$(echo -n 'admin:password' | base64)"
+DOC='{"@type":"Class","@id":"Role", "name":"xsd:string"}'
+curl -X POST -H 'Content-Type: application/json' -d "$DOC" -H "Authorization: Basic $BASE64" \
+"http://localhost:6363/api/document/admin/PeopleReferenceData/local/branch/[email protected]&message=InsertedDocument&graph_type=schema"
+```
+
+If you already have the schema element and want to update it, use the `PUT` keyword.
+
+### Creating a document on localhost
+
+* Instance name: admin
+* Data Product name: PeopleReferenceData
+* Branch name: main
+* Document type: Role
+* Document id: Role/ContentProducer
+* User: admin
+* Password: password
+* Provider: localhost:6363
+
+```bash
+BASE64="$(echo -n 'admin:password' | base64)"
+DOC='{"@type":"Role","@id":"Role/ContentProducer","name":"ContentProducer"}'
+curl -X POST -H 'Content-Type: application/json' -d "$DOC" -H "Authorization: Basic $BASE64" \
+"http://localhost:6363/api/document/admin/PeopleReferenceData/local/branch/[email protected]&message=InsertedDocument"
+```
+
+### Deleting a document on localhost
+
+```bash
+BASE64="$(echo -n 'admin:password' | base64)"
+DOCS='["Role/ContentProducer"]'
+curl -X DELETE -H 'Content-Type: application/json' -d "$DOCS" -H "Authorization: Basic $BASE64" \
+"http://localhost:6363/api/document/admin/PeopleReferenceData/local/branch/[email protected]&message=DeletedDocument"
+```
+
+## Cloud TerminusDB
+
+To connect to a cloud TerminusDB instance, such as with [DFRNT](https://dfrnt.com/hypergraph-content-studio), you need to mint an API token to your instance to get access to your data products, and documents stored in the branches of the data product.
+
+To connect to a cloud environment, we will assume you are connecting to the DFRNT TerminusDB cloud.
+
+### How to connect to cloud
+
+Below is how to use an API token to connect to a cloud TerminusDB instance at DFRNT. Note that there is a two-part to the api endpoints:
+
+1. api/hosted (can also be /api/dfrnt for instances connected via other API tokens)
+2. 000000000000-0000-0000-0000-00000001 (instance name)
+
+Then, instead of the `admin` organization, you will have a team that you connect to, which is a guid unless you have a team plan and share an instance.
+
+### Fetching a document (on a cloud instance with an API token)
+
+Example of how to fetch information about the ContentProducer Role in TerminusDB. The location of the document:
+
+* Instance name: 000000000000-0000-0000-0000-00000001 (it should be put twice)
+* Data Product name: PeopleReferenceData
+* Branch name: main
+* Document type: Role
+* Document id: Role/ContentProducer
+* Token: 000000000000-0000-0000-0000-00000001-000000000000-0000-0000-0000-00000001
+* Provider: https://dfrnt.com
+
+```bash
+API_TOKEN="000000000000-0000-0000-0000-00000001-000000000000-0000-0000-0000-00000001"
+curl -X GET -H "Authorization: Token $API_TOKEN" \
+https://dfrnt.com/api/hosted/000000000000-0000-0000-0000-00000001/api/document/000000000000-0000-0000-0000-00000001/PeopleReferenceData/local/branch/main?id=Role/ContentProducer
+```
+
+For more information about connecting to cloud instances, read [how to connect to the DFRNT API](https://support.dfrnt.com/portal/en/kb/articles/api). 
+
+
+
+
+

src/app/docs/terminusdb-db-cli-querying/page.md

@@ -0,0 +1,89 @@
+---
+title: How to use the terminusdb CLI query interface
+nextjs:
+  metadata:
+    title: How to use the terminusdb CLI query interface
+    description: Quick introduction to the terminusdb CLI WOQL Query interface which has a distinct syntax to other flavours.
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/terminusdb-db-cli-querying/
+media: []
+---
+
+This is a tutorial to learn the command line CLI interface to start exploring the local TerminusDB _system database. Be careful in not making incorrect or uncontrolled changes to the _system database as it can lock you out of your data products.
+
+*Disclaimer*: Do not run this tutorial with data that you do care about. Here be dragons. You have hereby been warned!
+
+The local TerminusDB database CLI has a WOQL query interface built in, with a distinct syntax to other flavours. When working with a local TerminusDB instance, it is often handy to perform offline commands against it, or extract information in a data pipeline for ML/Ops.
+
+This syntax is for advanced users who have significant experience with TerminusDB and WOQL. If you are new to TerminusDB, we recommend starting with the [TerminusDB Quickstart](/docs/get-started-with-terminusdb/).
+
+## Syntax
+
+The syntax of the WOQL query interface is distinct from other flavours, and is based more closely on the Prolog syntax. The WOQL logic is the same, but the syntax is different, especially for and, triple and other predicates expected in WOQL.
+
+This documentation is incomplete and a stub. PRs are welcome to strengthen it and make it more complete. It only covers the syntax differences. Refer to the [WOQL Javascript syntax](/docs/javascript-woql/) as the main language interface.
+
+We will use the system database as the example database for this guide as it's available on the local system.
+
+### Getting started with a simple query
+
+An example for finding the databases in the system:
+
+```bash
+./terminusdb query _system "(
+  t(Database,rdf:type,'@schema':'UserDatabase')
+)"
+```
+
+A couple of notes:
+* All variables must start with a capital letter
+* The string values must be in single quotes
+* IRIs with prefixes must have the two portions quoted independently with a colon inbetween due to the `@` sign
+* the `triple` syntax is `t(A,B,C)` instead of `triple(A,B,C)`
+* the `quad` syntax is `t(A,B,C,schema)` instead of `quad(A,B,C,schema)`
+* the `and` syntax is `(statementA,statementB)` instead of `and(A,B)`
+* the `or` syntax is `(statementA;statementB)` instead of `or(A,B)`
+
+### Finding which capabilities users have
+
+The terminusdb client does not yet have the ability to find which capabilities a user has on which databases or organizations. This command queries them.
+
+```bash
+./terminusdb query _system "select([User,Role,Scope],(
+  t(Capability,rdf:type,'@schema':'Capability'),
+  t(Capability,role,Role),
+  t(Capability,scope,Scope),
+  t(User,capability,Capability),
+  User='User/[email protected]'
+))"
+```
+
+Some additional notes:
+
+* select works by binding variables to be returned
+* `t()` is used to bind triples
+* to bind a specific value, use bind variables to specific values using `=`
+* Note that the variables are unified by the values stored in the database
+
+Or, to see the capabilities of all users, don't check for a specific user:
+
+```bash
+./terminusdb query _system "select([User,Role,Scope],(
+  t(Capability,rdf:type,'@schema':'Capability'),
+  t(Capability,role,Role),
+  t(Capability,scope,Scope),
+  t(User,capability,Capability)
+))"
+```
+
+### Graph Specifications, GRAPH_SPEC
+
+To specify a graph to interact with, use the graph_spec before the query. Here are a couple of ways to specify a graph. The admin team is the default team on local TerminusDB instances.
+
+* `_system`: the system database
+* `org/data_product`: main of a specific data product
+* `admin/data_product/local/branch/main` the main branch of the data product data_product in the admin organisation/team
+* `admin/data_product/local/commit/9w8hk3y6rb8tjdy961ed3i536ntkqd8` a specific commit in the data product data_product
+

src/lib/navigation.ts

@@ -170,10 +170,13 @@ export const navigation: Navigation[] = [
               },
             ],
           },
-
           {
             title: 'Document Interface',
             links: [
+              {
+                title: 'HTTP Documents API',
+                href: '/docs/http-documents-api',
+              },
               {
                 title: 'Document Graph Howto',
                 href: '/docs/document-graph-api',
@@ -620,6 +623,12 @@ export const navigation: Navigation[] = [
           {
             title: 'TerminusDB CLI Reference',
             href: '/docs/terminusdb-cli-commands',
+            links: [
+              {
+                title: 'TerminusDB CLI Querying',
+                href: '/docs/terminusdb-db-cli-querying',
+              },
+            ],
           },
           {
             title: 'Git-for-Data Reference',