[Feature] CLI docs (#6362)

* 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]>
OpenBB-finance · May 14, 2024 · 8d060dc · 8d060dc
1 parent a116d9b
commit 8d060dc
Show file tree

Hide file tree

Showing 26 changed files with 1,458 additions and 19 deletions.
diff --git a/cli/openbb_cli/controllers/settings_controller.py b/cli/openbb_cli/controllers/settings_controller.py
@@ -21,10 +21,7 @@ class SettingsController(BaseController):
     CHOICES_COMMANDS: List[str] = [
         "interactive",
         "cls",
-        "watermark",
         "promptkit",
-        "thoughts",
-        "reporthtml",
         "exithelp",
         "rcontext",
         "richpanel",

diff --git a/website/content/cli/_category_.json b/website/content/cli/_category_.json
@@ -0,0 +1,4 @@
+{
+    "label": "OpenBB CLI",
+    "position": 2
+}
diff --git a/website/content/cli/commands-and-arguments.md b/website/content/cli/commands-and-arguments.md
@@ -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.
diff --git a/website/content/cli/configuration.md b/website/content/cli/configuration.md
@@ -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  |
diff --git a/website/content/cli/data-sources.md b/website/content/cli/data-sources.md
@@ -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"
+            },
+            ...
+        }
+    }
+}
+```
diff --git a/website/content/cli/hub.md b/website/content/cli/hub.md
@@ -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
+```