Skip to content

Commit

Permalink
[Feature] CLI docs (#6362)
Browse files Browse the repository at this point in the history
* cli docs website

* changes

* remove unused feat flags

* typo

* yeet stuff that can't be used

* some progress

* Add home screenshot

* screenshots.md

* fix links

* new cards for cli pages

* start config page

* more updates

* Add screenshots

* flatten some things.

* fix link

* some more updates

* some routine stuff

* codespell

* cli color

* results in the global commands

* increase codeBlock line-height

* remove platform warning, obb is a class

* minor change, danger warning

* typo?

* Data processing commands

---------

Co-authored-by: Danglewood <[email protected]>
Co-authored-by: Diogo Sousa <[email protected]>
  • Loading branch information
3 people committed May 14, 2024
1 parent a116d9b commit 8d060dc
Show file tree
Hide file tree
Showing 26 changed files with 1,458 additions and 19 deletions.
3 changes: 0 additions & 3 deletions cli/openbb_cli/controllers/settings_controller.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,7 @@ class SettingsController(BaseController):
CHOICES_COMMANDS: List[str] = [
"interactive",
"cls",
"watermark",
"promptkit",
"thoughts",
"reporthtml",
"exithelp",
"rcontext",
"richpanel",
Expand Down
4 changes: 4 additions & 0 deletions website/content/cli/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "OpenBB CLI",
"position": 2
}
76 changes: 76 additions & 0 deletions website/content/cli/commands-and-arguments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
title: Commands And Arguments
sidebar_position: 4
description: This page explains how to enter commands and arguments into the OpenBB CLI.
keywords:
- help arguments
- auto-complete
- global commands
- support command
- reset command
- command line interface
- metadata
- cli
- parameters
- functions
- commands
- options
---

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

<HeadTitle title="Commands And Arguments | OpenBB CLI Docs" />

Commands are displayed on-screen in a lighter colour, compared with menu items, and they will not be prefaced with, `>`.

Functions have a variety of parameters that differ by endpoint and provider. The --help dialogue will provide guidance on nuances of any particular command.

The available data sources for each command are displayed on the right side of the screen, and are selected with the `--provider` argument.

## Help arguments

The `help` command shows the current menu. The screen will display all the commands and menus that exist, including a short description for each of these.

Adding `--help`, or `-h`, to any command will display the description and parameters for that particular function.

## Entering Parameters

Parameters are all defined through the same pattern, --argument, followed by a space, and then the value.

If the parameter is a boolean (true/false), there is no value to enter. Adding the --argument flags the parameter to be the opposite of its default state.

Use the auto-complete to prompt choices and reduce the amount of keystrokes required to run a complex function.

## Auto-complete

The OpenBB CLI is equipped with an auto completion engine that presents choices based on the current menu and command. Whenever you start typing, suggestion prompts will appear for existing commands and menus. When the command contains arguments, pressing the `space bar` after typing the command will present the list of available arguments.

This functionality dramatically reduces the number of key strokes required to perform tasks and, in many cases, eliminates the need to consult the help dialogue for reminders. Choices - where they are bound by a defined list - are scrollable with the up and down arrow keys.

## Global commands

These are commands that can be used throughout the CLI and will work regardless of the menu where they belong.

### Help

`--help`, or `-h` can be attached to any command, as described above.

### CLS

The `cls` command clears the entire CLI screen.

### Quit

The `quit` command (can also use `q` or `..`) allows to leave the current menu to go one menu above. If the user is on the root, that will mean leaving the CLI.

### Exit

The `exit` command allows the user to exit the CLI.

### Reset

The `reset` command will reset the CLI to its default state. This is specially useful for development so you can refresh the CLI without having to close and open it again.

### Results

The `results` command will display the stack of `OBBjects` that have been generated during the session, which can be later injected on the data processing commands.
66 changes: 66 additions & 0 deletions website/content/cli/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Configuration & Settings
sidebar_position: 5
description: This documentation page details the various settings and feature flags used to customize the OpenBB CLI.
keywords:
- Settings Menu
- Feature Flags Menu
- customize CLI
- alter CLI behaviour
- environment variables
- Documentation
- OpenBB Platform CLI
- preferences
- user
---

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

<HeadTitle title="Configuration & Settings - | OpenBB CLI Docs" />

In addition to the OpenBB Platform's `user_settings.json` file, described [here](/platform/usage/settings_and_environment_variables), there are settings and environment variables affecting the CLI only.

:::important
API credentials are defined in the `user_settings.json` file.

Find all data providers [here](/platform/extensions/data_extensions), and manage all your credentials directly on the [OpenBB Hub](https://my.openbb.co/app/platform/credentials).

Define default data sources by following the pattern outlined [here](data-sources)
:::

## Settings Menu

The `/settings` menu provides methods for customizing the look and feel of the CLI. The menu is divided into two sections:

- Feature Flags
- On/Off status is reflected by red/green text.
- Status is toggled by entering the item as a command.
- Preferences
- Choices and options will be presented as a typical function.

### Feature Flags

| Feature Flags | Description |
| :----------- | :--------------------------------------------------------------- |
| `interactive` | Enable/disable interactive tables. Disabling prints the table directly on the CLI screen. |
| `cls` | Clear the screen after each command. Default state is off. |
| `promptkit` | Enable auto complete and history. Default state is on. |
| `richpanel` | Displays a border around menus. Default state is on. |
| `tbhint` | Display usage hints in the bottom toolbar. Default state is on. |
| `exithelp` | Automatically print the screen after navigating back one menu. Default state is off. |
| `overwrite` | Automatically overwrite exported files with the same name. Default state is off. |
| `obbject_msg` | Displays a message whenever a new result is added to the registry. Default state is off. |
| `version` | Displays the currently installed version number in the bottom right corner. |

### Preferences

| Preferences | Description |
| :----------- | :--------------------------------------------------------------- |
| `console_style` | apply a custom rich style to the CLI |
| `flair` | choose flair icon |
| `timezone` | pick timezone |
| `language` | translation language |
| `n_rows` | number of rows to show on non interactive tables |
| `n_cols` | number of columns to show on non interactive tables |
| `obbject_res` | define the maximum number of obbjects allowed in the registry |
| `obbject_display` | define the maximum number of cached results to display on the help menu |
113 changes: 113 additions & 0 deletions website/content/cli/data-sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
---
title: Data Sources
sidebar_position: 7
description: This page explains how to select a provider for any specific command, and set a default source for a route.
keywords:
- Terminal
- CLI
- provider
- API keys
- FinancialModelingPrep
- Polygon
- AlphaVantage
- Intrinio
- YahooFinance
- source
- data
- default
---

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

<HeadTitle title="Data Sources | OpenBB CLI Docs" />

Many commands have multiple data sources associated with it. This page describes how to select from multiple providers.

:::important
API credentials are defined in the `user_settings.json` file.

Find all data providers [here](/platform/extensions/data_extensions), and manage all your credentials directly on the [OpenBB Hub](https://my.openbb.co/app/platform/credentials).
:::

## Data Source In-Command

To specify the data vendor for that particular command, use the `--provider` argument.

Parameter choices can be viewed from the help dialogue, `-h` or `--help`.

```console
/equity/price/historical -h
```

```console
usage: historical --symbol SYMBOL [SYMBOL ...] [--interval INTERVAL] [--start_date START_DATE] [--end_date END_DATE] [--chart]
[--provider {fmp,intrinio,polygon,tiingo,yfinance}] [--start_time START_TIME] [--end_time END_TIME] [--timezone TIMEZONE]
[--source {realtime,delayed,nasdaq_basic}] [--sort {asc,desc}] [--limit LIMIT] [--extended_hours] [--include_actions]
[--adjustment {splits_and_dividends,unadjusted,splits_only}] [--adjusted] [--prepost] [-h] [--export EXPORT]
[--sheet-name SHEET_NAME [SHEET_NAME ...]]

Get historical price data for a given stock. This includes open, high, low, close, and volume.

options:
--interval INTERVAL Time interval of the data to return.
--start_date START_DATE
Start date of the data, in YYYY-MM-DD format.
--end_date END_DATE End date of the data, in YYYY-MM-DD format.
--chart Whether to create a chart or not, by default False.
--provider {fmp,intrinio,polygon,tiingo,yfinance}
The provider to use for the query, by default None.
If None, the provider specified in defaults is selected or 'fmp' if there is
no default.
--extended_hours Include Pre and Post market data. (provider: polygon, yfinance)
--adjustment {splits_and_dividends,unadjusted,splits_only}
The adjustment factor to apply. Default is splits only. (provider: polygon, yfinance)
-h, --help show this help message
--export EXPORT Export raw data into csv, json, xlsx and figure into png, jpg, pdf, svg
--sheet-name SHEET_NAME [SHEET_NAME ...]
Name of excel sheet to save data to. Only valid for .xlsx files.

required arguments:
--symbol SYMBOL [SYMBOL ...]
Symbol to get data for. Multiple comma separated items allowed for provider(s): fmp, polygon, tiingo, yfinance.

intrinio:
--start_time START_TIME
Return intervals starting at the specified time on the `start_date` formatted as 'HH:MM:SS'.
--end_time END_TIME Return intervals stopping at the specified time on the `end_date` formatted as 'HH:MM:SS'.
--timezone TIMEZONE Timezone of the data, in the IANA format (Continent/City).
--source {realtime,delayed,nasdaq_basic}
The source of the data.

polygon:
--sort {asc,desc} Sort order of the data. This impacts the results in combination with the 'limit' parameter. The results are always returned in ascending order by date.
--limit LIMIT The number of data entries to return.

yfinance:
--include_actions Include dividends and stock splits in results.
```

:::note
Provider-specific parameters are listed at the bottom of the print out. They are ignored when entered, if it is not supported by the selected provider.
:::

## Setting The Default Source

The default data source for each command (where multiple sources are available) can be defined within the user configuration file: `/home/your-user/.openbb_platform/user_settings.json`.

Set the default data provider for the `/equity/price/historical` command by adding the following line to your `user_settings.json` file:

```json
{
"defaults": {
"routes": {
"/equity/price/historical": {
"provider": "fmp"
},
"/equity/fundamental/balance": {
"provider": "polygon"
},
...
}
}
}
```
111 changes: 111 additions & 0 deletions website/content/cli/hub.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
---
title: Hub Synchronization
sidebar_position: 6
description: This page outlines the `/account` menu within the OpenBB CLI, and integrations with the OpenBB Hub.
keywords:
- OpenBB Platform CLI
- OpenBB Hub
- Registration
- Login process
- API Keys management
- Theme
- Style
- Dark
- Light
- Script Routines
- Personal Access Tokens
- PAT
- Credentials
- Customization
---

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

<HeadTitle title="Hub Synchronization | OpenBB Platform CLI Docs" />

This page outlines the `/account` menu within the OpenBB CLI and integrations with the OpenBB Hub.

## Registration

To get started, you'll need to create an account on the OpenBB Hub by visiting [https://my.openbb.co](https://my.openbb.co)

By registering with the OpenBB Hub, you can easily access our products on multiple devices and maintain consistent settings for an improved user experience.

## Login

Once you're successfully registered on the OpenBB Hub, you can log in to access all the benefits it has to offer.

:::tip
OpenBB recommends logging in via the Personal Access Token (PAT) method. This revokable token allows users to login without transmitting any personally identifiable information, like an email address, which makes it an ideal solution for shared machines and public network connections.
:::

To login, enter the `/account` menu and then use the `login` command with your choice of login method.

### PAT

```console
/account
login --pat REPLACE_WITH_PAT
```

### Email & Password

```console
/account
login --email [email protected] --password totallysecurepassword
```

## API Keys

The OpenBB Platform acts as a mediator between users and data providers.

With an OpenBB Hub account, you can manage your API keys on [this page](https://my.openbb.co/app/platform/credentials).

Upon logging in, the CLI will automatically retrieve the API keys associated with your account.

If you have not saved them on the OpenBB Hub, they will be loaded from your local environment by default.

:::danger
If an API key is saved on the OpenBB Hub, it will take precedence over the local environment key.
:::

The CLI will need to be restarted, or refreshed, when changes are made on the Hub.

## Theme Styles

Theme styles correspond to the ability to change the terminal "skin" (i.e. coloring of the `menu`, `commands`, `data source`, `parameters`, `information` and `help`), as well as the chart and table styles.

In the OpenBB Hub, you can select the text colours for the CLI. After customizing:
- Download the theme to your styles directory (`/home/your-user/OpenBBUserData/styles/user`).
- Apply it by selecting the style from the `/settings` menu.

```console
/settings
console_style -s openbb_config
```

Replace `openbb_config` with the name of the downloaded (JSON) file.

## Script Routines

The OpenBB Hub allows users to create, edit, manage, and share their script routines that can be run in the OpenBB Platform CLI.

The "Download" button will save the file locally. Add it to `/home/your-user/OpenBBUserData/routines`, for the script to populate as a choice for the `exe` command on next launch.

## Refresh

The `refresh` command will update any changes without the need to logout and login.

```console
/account
refresh
```

## Logout

Logging out will restore any local credentials and preferences defined in the `user_settings.json` file.

```console
/account
logout
```
Loading

0 comments on commit 8d060dc

Please sign in to comment.