io7m | single-page | multi-page | epub | Cardant User Manual 1.0.0-beta0001
7. Shell
Previous
7. Shell
Up
7.2. Shell Command Reference
Next

# 7.1. Usage

- 7.1.1. Overview
- 7.1.2. Tab Completion
- 7.1.3. History
- 7.1.4. Quoting
- 7.1.5. Newlines
- 7.1.6. Formatter
- 7.1.7. Bookmarks
- 7.1.8. Searching
  - 7.1.8.1. Description
  - 7.1.8.2. Name Matching
  - 7.1.8.3. Type Matching
  - 7.1.8.4. Description Matching
  - 7.1.8.5. Media Type Matching
  - 7.1.8.6. Serial Matching
  - 7.1.8.7. Package Matching
  - 7.1.8.8. Field Matching

## 7.1.1. Overview

1
In addition to the API access the server provides, the cardant package includes an interactive command-line shell for performing tasks.
2
The shell is started using the shell command. The shell supports basic tab-completion and history accessed with the up and down arrows.

## 7.1.2. Tab Completion

1
When running on an appropriate terminal, the shell supports tab completion for command and most command arguments. Begin typing the name of a command, or the name of a command argument, and then press tab. A set of completion options will be displayed.

### 7.1.2.2. Command Completion

### 7.1.2.3. Argument Completion

## 7.1.3. History

1
When running on an appropriate terminal, the command shell stores the history of commands in memory (the history is not saved to disk, for security reasons). Press the up and down arrows to navigate to previously executed commands.

## 7.1.4. Quoting

1
Arguments to shell commands may be quoted using the " or ' characters. This is required when calling commands that take arguments that may need to contain strings.

### 7.1.4.2. Strings

## 7.1.5. Newlines

1
Typically, the ENTER key ends the current line. This will cause the shell to interpret the contents of a line as a command and execute it. Pressing ALT+ENTER inserts an actual newline character without executing the command. This can be useful if an argument to a command needs to contain a newline character:

### 7.1.5.2. Strings

3
When in this mode, the cursor can be moved around freely with the arrow keys to allow for editing lines. Pressing the ENTER key ends the multiline editing mode and executes the command.

## 7.1.6. Formatter

1
The shell provides different formatting options for tabular data.

### 7.1.6.2. Formatters

Name | Description
--- | ---
PRETTY | Provides pretty Unicode tables.
RAW | Provides raw tables.

3
The formatter can be set using the set command.

### 7.1.6.4. Example

    [cardant]$ set --formatter PRETTY
    [cardant]$ audit-search-begin
    Search results: Page 1 of 1
    ┌────┬──────────────────────────────────────┬────────────────┬─────────────────────────────┬─────────────────────────────────────────────────────────────────────────┐
    │ ID │ Owner                                │ Type           │ Time                        │ Data                                                                    │
    ├────┼──────────────────────────────────────┼────────────────┼─────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤
    │ 1  │ c5574d46-7413-43c8-b6db-31001c382ca3 │ USER_LOGGED_IN │ 2023-12-21T11:30:11.171839Z │ {UserAgent=com.io7m.cardant.client/0.0.1-SNAPSHOT, Host=10.1.6.1:53236} │
    └────┴──────────────────────────────────────┴────────────────┴─────────────────────────────┴─────────────────────────────────────────────────────────────────────────┘

    [cardant]$ set --formatter RAW
    [cardant]$ audit-search-begin
    # Search results: Page 1 of 1
    #--------------------------------
    1 c5574d46-7413-43c8-b6db-31001c382ca3 USER_LOGGED_IN 2023-12-21T11:30:11.171839Z {UserAgent=com.io7m.cardant.client/0.0.1-SNAPSHOT, Host=10.1.6.1:53236}

## 7.1.7. Bookmarks

1
The shell allows for setting server bookmarks. A server bookmark is essentially the information required to log in to a particular server as a particular user.
2
Bookmarks can be created with the bookmark-put command, listed with the bookmark-list command, and used with the bookmark-login command.

### 7.1.7.3. Example

    [cardant]$ bookmark-put --user example --password F7B7D37C620C70BF03353148582AC97D --hostname 10.1.6.1 --name local0

    [cardant]$ bookmark-list
    ┌─────────────────┬─────────────────────────┬───────┬───────┬──────────────────┐
    │ Name            │ Host                    │ Port  │ TLS   │ User             │
    ├─────────────────┼─────────────────────────┼───────┼───────┼──────────────────┤
    │ local0          │ 10.1.6.1                │ 30000 │ false │ example          │
    └─────────────────┴─────────────────────────┴───────┴───────┴──────────────────┘
    [cardant]$ bookmark-login --name local0

    [cardant]$ self
    User ID: c5574d46-7413-43c8-b6db-31001c382ca3
    ┌────────────────────────────────────────────────────────────────────────────────┐
    │ Role                                                                           │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ audit.reader                                                                   │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.admin                                                                │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.files.reader                                                         │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.files.writer                                                         │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.items.reader                                                         │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.items.writer                                                         │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.locations.reader                                                     │
    ├────────────────────────────────────────────────────────────────────────────────┤
    │ inventory.locations.writer                                                     │
    └────────────────────────────────────────────────────────────────────────────────┘

## 7.1.8. Searching

## 7.1.8.1. Description

1
The cardant package exposes many commands for searching the database.
2
All search commands in the cardant package provide automatic pagination. Searches are performed by beginning a search with a begin command which will yield the first page of results. Searches are then continued with next and previous commands which will return the next and previous pages of results, respectively. It is an error to try to execute a next or previous command without first having executed a begin command.
3
Each page of search results includes the number of the current page, and the number of pages of search results available. Attempting to seek beyond the end of the set of pages with a next command is not an error; the server will simply repeatedly return the last page in the set. Similarly, attempting to seek before the first page of results with a previous command will simply return the first page of results, repeatedly.
4
The search commands typically accept different filtering expressions to allow for very rich search capabilities. The syntactic forms of all the different expression types are listed in the following sections of the documentation, and can also be inspected using the syntax-list and syntax-show shell commands.

## 7.1.8.2. Name Matching

1
A name match expression is an expression used to filter search results. The expression is evaluated using the object's name as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.2.3. Forms

- with-any-name
- (with-name-equal-to n)
- (with-name-not-equal-to n)
- (with-name-similar-to n)
- (with-name-not-similar-to n)

4
Expressions have the following semantics, given in terms of a match_name_evaluate function:

### 7.1.8.2.5. Semantics

    match_name_evaluate with-any-name n                 ⇒ true
    match_name_evaluate (with-name-equal-to m) n        ⇒ n = m
    match_name_evaluate (with-name-not-equal-to m) n    ⇒ n ≠ m
    match_name_evaluate (with-name-similar-to m) n      ⇒ n ≃ m
    match_name_evaluate (with-name-not-similar-to m) n  ⇒ not (n ≃ m)

### 7.1.8.2.6. Semantics Explanation

- An expression with-any-name always evaluates to true.
- For all names m, (with-name-equal-to n) m evaluates to true iff m = n.
- For all names m, (with-name-not-equal-to n) m evaluates to true iff m ≠ n.
- For all names m, (with-name-similar-to n) m evaluates to true iff m is sufficiently similar to n according to an implementation-defined, language-specific similarity function.
- For all names m, (with-name-not-similar-to n) m evaluates to true iff m is not sufficiently similar to n according to an implementation-defined, language-specific similarity function.

7
Specifically, the "similarity" function is currently implemented in terms of PostgreSQL's full text search functionality.

### 7.1.8.2.8. Syntax

    match_name ::=
        "with-any-name"
      | "(" "with-name-equal-to" <name> ")"
      | "(" "with-name-not-equal-to" <name> ")"
      | "(" "with-name-similar-to" <string> ")"
      | "(" "with-name-not-similar-to" <string> ")"
      ;

## 7.1.8.3. Type Matching

1
A type match expression is an expression used to filter search results. The expression is evaluated using the object's set of types as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.3.3. Forms

- with-any-types
- (with-types-equal-to n)
- (with-types-not-equal-to n)
- (with-types-superset-of n)
- (with-types-subset-of n)
- (with-types-overlapping n)

4
Expressions have the following semantics, given in terms of a match_type_evaluate function:

### 7.1.8.3.5. Semantics

    match_name_evaluate with-any-type s                 ⇒ true
    match_name_evaluate (with-types-to t) s             ⇒ s = t
    match_name_evaluate (with-types-not-equal-to t) s   ⇒ s ≠ t
    match_name_evaluate (with-types-superset-of t) s    ⇒ s ⊆ t
    match_name_evaluate (with-types-subset-of t) s      ⇒ s ⊇ t
    match_name_evaluate (with-types-overlapping t) s    ⇒ ∃ e. e ∈ t ∧ e ∈ s

### 7.1.8.3.6. Semantics Explanation

- An expression with-any-types always evaluates to true.
- For all descriptions s, (with-types-equal-to t) s evaluates to true iff t = s. Note that sets are not ordered.
- For all descriptions s, (with-types-not-equal-to t) s evaluates to true iff s ≠ t. Note that sets are not ordered.
- For all descriptions s, (with-types-subset-of t) s evaluates to true iff s is a subset of t.
- For all descriptions s, (with-types-superset-of t) s evaluates to true iff s is a superset of t.
- For all descriptions s, (with-types-overlapping t) s evaluates to true iff there exists some element e that is present in both s and t.

### 7.1.8.3.7. Syntax

    match_type ::=
        "with-any-type"
      | "(" "with-types-equal-to" <type-record-identifier> [<type-record-identifier>, ...] ")"
      | "(" "with-types-not-equal-to" <type-record-identifier> [<type-record-identifier>, ...] ")"
      | "(" "with-types-superset-of" <type-record-identifier> [<type-record-identifier>, ...] ")"
      | "(" "with-types-subset-of" <type-record-identifier> [<type-record-identifier>, ...] ")"
      | "(" "with-types-overlapping" <type-record-identifier> [<type-record-identifier>, ...] ")"
      ;

## 7.1.8.4. Description Matching

1
A description match expression is an expression used to filter search results. The expression is evaluated using the object's description as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.4.3. Forms

- with-any-description
- (with-description-equal-to n)
- (with-description-not-equal-to n)
- (with-description-similar-to n)
- (with-description-not-similar-to n)

4
Expressions have the following semantics, given in terms of a match_description_evaluate function:

### 7.1.8.4.5. Semantics

    match_description_evaluate with-any-description n                 ⇒ true
    match_description_evaluate (with-description-equal-to m) n        ⇒ n = m
    match_description_evaluate (with-description-not-equal-to m) n    ⇒ n ≠ m
    match_description_evaluate (with-description-similar-to m) n      ⇒ n ≃ m
    match_description_evaluate (with-description-not-similar-to m) n  ⇒ not (n ≃ m)

### 7.1.8.4.6. Semantics Explanation

- An expression with-any-description always evaluates to true.
- For all descriptions m, (with-description-equal-to n) m evaluates to true iff m = n.
- For all descriptions m, (with-description-not-equal-to n) m evaluates to true iff m ≠ n.
- For all descriptions m, (with-description-similar-to n) m evaluates to true iff m is sufficiently similar to n according to an implementation-defined, language-specific similarity function.
- For all descriptions m, (with-description-not-similar-to n) m evaluates to true iff m is not sufficiently similar to n according to an implementation-defined, language-specific similarity function.

7
Specifically, the "similarity" function is currently implemented in terms of PostgreSQL's full text search functionality.

### 7.1.8.4.8. Syntax

    match_description ::=
        "with-any-description"
      | "(" "with-description-equal-to" <description> ")"
      | "(" "with-description-not-equal-to" <description> ")"
      | "(" "with-description-similar-to" <string> ")"
      | "(" "with-description-not-similar-to" <string> ")"
      ;

## 7.1.8.5. Media Type Matching

1
A media type match expression is an expression used to filter search results. The expression is evaluated using the object's media type as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.5.3. Forms

- with-any-mediatype
- (with-mediatype-equal-to n)
- (with-mediatype-not-equal-to n)
- (with-mediatype-similar-to n)
- (with-mediatype-not-similar-to n)

4
Expressions have the following semantics, given in terms of a match_mediatype_evaluate function:

### 7.1.8.5.5. Semantics

    match_mediatype_evaluate with-any-mediatype n                 ⇒ true
    match_mediatype_evaluate (with-mediatype-equal-to m) n        ⇒ n = m
    match_mediatype_evaluate (with-mediatype-not-equal-to m) n    ⇒ n ≠ m
    match_mediatype_evaluate (with-mediatype-similar-to m) n      ⇒ n ≃ m
    match_mediatype_evaluate (with-mediatype-not-similar-to m) n  ⇒ not (n ≃ m)

### 7.1.8.5.6. Semantics Explanation

- An expression with-any-mediatype always evaluates to true.
- For all media types m, (with-mediatype-equal-to n) m evaluates to true iff m = n.
- For all media types m, (with-mediatype-not-equal-to n) m evaluates to true iff m ≠ n.
- For all media types m, (with-mediatype-similar-to n) m evaluates to true iff m is sufficiently similar to n according to an implementation-defined, language-specific similarity function.
- For all media types m, (with-mediatype-not-similar-to n) m evaluates to true iff m is not sufficiently similar to n according to an implementation-defined, language-specific similarity function.

7
Specifically, the "similarity" function is currently implemented in terms of PostgreSQL's full text search functionality.

### 7.1.8.5.8. Syntax

    match_mediatype ::=
        "with-any-mediatype"
      | "(" "with-mediatype-equal-to" <mediatype> ")"
      | "(" "with-mediatype-not-equal-to" <mediatype> ")"
      | "(" "with-mediatype-similar-to" <string> ")"
      | "(" "with-mediatype-not-similar-to" <string> ")"
      ;

## 7.1.8.6. Serial Matching

1
A serial match expression is an expression used to filter search results. The expression is evaluated using the object's serial number as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.6.3. Forms

- with-any-serial
- (with-serial-equal-to n)
- (with-serial-not-equal-to n)

4
Expressions have the following semantics, given in terms of a match_serial_evaluate function:

### 7.1.8.6.5. Semantics

    match_serial_evaluate with-any-serial n                 ⇒ true
    match_serial_evaluate (with-serial-equal-to m) n        ⇒ n = m
    match_serial_evaluate (with-serial-not-equal-to m) n    ⇒ n ≠ m

### 7.1.8.6.6. Semantics Explanation

- An expression with-any-serial always evaluates to true.
- For all descriptions m, (with-serial-equal-to n) m evaluates to true iff m = n.
- For all descriptions m, (with-serial-not-equal-to n) m evaluates to true iff m ≠ n.

7
Specifically, the "similarity" function is currently implemented in terms of PostgreSQL's full text search functionality.

### 7.1.8.6.8. Syntax

    match_serial ::=
        "with-any-serial"
      | "(" "with-serial-equal-to" <serial> ")"
      | "(" "with-serial-not-equal-to" <serial> ")"
      ;

## 7.1.8.7. Package Matching

1
A package match expression is an expression used to filter search results. The expression is evaluated using the object's type package as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.7.3. Forms

- with-any-package
- (with-package-equal-to n)
- (with-package-not-equal-to n)

4
Expressions have the following semantics, given in terms of a match_package_evaluate function:

### 7.1.8.7.5. Semantics

    match_package_evaluate with-any-package n                 ⇒ true
    match_package_evaluate (with-package-equal-to m) n        ⇒ n = m
    match_package_evaluate (with-package-not-equal-to m) n    ⇒ n ≠ m

### 7.1.8.7.6. Semantics Explanation

- An expression with-any-package always evaluates to true.
- For all descriptions m, (with-package-equal-to n) m evaluates to true iff m = n.
- For all descriptions m, (with-package-not-equal-to n) m evaluates to true iff m ≠ n.

### 7.1.8.7.7. Syntax

    match_package ::=
        "with-any-package"
      | "(" "with-package-equal-to" <package> ")"
      | "(" "with-package-not-equal-to" <package> ")"
      ;

## 7.1.8.8. Field Matching

1
A field match expression is an expression used to filter search results. The expression is evaluated using the object's field name as input and the object is included in search results if the expression evaluates to true.
2
An expression takes one of the following forms:

### 7.1.8.8.3. Forms

- with-any-field
- (with-field-equal-to n)
- (with-field-not-equal-to n)

4
Expressions have the following semantics, given in terms of a match_field_evaluate function:

### 7.1.8.8.5. Semantics

    match_field_evaluate with-any-field n                 ⇒ true
    match_field_evaluate (with-field-equal-to m) n        ⇒ n = m
    match_field_evaluate (with-field-not-equal-to m) n    ⇒ n ≠ m

### 7.1.8.8.6. Semantics Explanation

- An expression with-any-field always evaluates to true.
- For all descriptions m, (with-field-equal-to n) m evaluates to true iff m = n.
- For all descriptions m, (with-field-not-equal-to n) m evaluates to true iff m ≠ n.

### 7.1.8.8.7. Syntax

    match_field ::=
        "with-any-field"
      | "(" "with-field-equal-to" <type-record-field-identifier> ")"
      | "(" "with-field-not-equal-to" <type-record-field-identifier> ")"
      ;

7. Shell
Previous
7. Shell
Up
7.2. Shell Command Reference
Next
io7m | single-page | multi-page | epub | Cardant User Manual 1.0.0-beta0001