io7m | single-page | multi-page | epub | Cardant User Manual 0.0.1
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. Search Pagination
- 7.1.7. Formatter
- 7.1.8. Bookmarks

## 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. Search Pagination

1
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.
2
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.

## 7.1.7. Formatter

1
The shell provides different formatting options for tabular data.

### 7.1.7.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.7.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.8. 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.8.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. Shell
Previous
7. Shell
Up
7.2. Shell Command Reference
Next
io7m | single-page | multi-page | epub | Cardant User Manual 0.0.1