Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature] CLI docs #6362

Merged
merged 42 commits into from
May 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
a440064
cli docs website
hjoaquim May 2, 2024
1c366b1
Merge branch 'develop' into feature/docs-cli
hjoaquim May 2, 2024
f7e5ce0
changes
hjoaquim May 2, 2024
bb5977c
remove unused feat flags
hjoaquim May 2, 2024
768a24e
typo
hjoaquim May 2, 2024
47fb848
Merge branch 'develop' of https://github.com/OpenBB-finance/OpenBBTer…
deeleeramone May 7, 2024
5c298f1
yeet stuff that can't be used
deeleeramone May 8, 2024
b6365d2
Merge branch 'develop' into feature/docs-cli
deeleeramone May 8, 2024
6c95a2e
some progress
deeleeramone May 8, 2024
736a9db
Add home screenshot
deeleeramone May 8, 2024
2cfd659
screenshots.md
deeleeramone May 8, 2024
a8fe30b
Merge remote-tracking branch 'OpenBB-finance/develop' into feature/do…
hjoaquim May 9, 2024
35f4f17
Merge branch 'feature/docs-cli' of github.com:OpenBB-finance/OpenBBTe…
hjoaquim May 9, 2024
2a12031
fix links
hjoaquim May 9, 2024
9e0f81b
new cards for cli pages
hjoaquim May 9, 2024
30a0f5d
Merge branch 'develop' into feature/docs-cli
deeleeramone May 9, 2024
2fd3f28
Merge branch 'develop' into feature/docs-cli
deeleeramone May 9, 2024
fda14b8
start config page
deeleeramone May 9, 2024
6977058
more updates
deeleeramone May 10, 2024
b07f3eb
Add screenshots
deeleeramone May 10, 2024
98a8a4f
flatten some things.
deeleeramone May 10, 2024
859dec9
Merge branch 'feature/docs-cli' of https://github.com/OpenBB-finance/…
deeleeramone May 10, 2024
0f08f0d
fix link
deeleeramone May 10, 2024
a144a18
merge branch develop
deeleeramone May 10, 2024
daf959f
some more updates
deeleeramone May 11, 2024
c856cd9
merge branch develop
deeleeramone May 11, 2024
6197216
some routine stuff
deeleeramone May 12, 2024
eb6a71d
codespell
deeleeramone May 12, 2024
af2f6c2
Merge branch 'develop' into feature/docs-cli
hjoaquim May 13, 2024
ecc6b3b
Merge branch 'develop' into feature/docs-cli
deeleeramone May 13, 2024
a3d51a0
Merge branch 'develop' into feature/docs-cli
hjoaquim May 14, 2024
c03b2be
Merge branch 'develop' into feature/docs-cli
hjoaquim May 14, 2024
aeed807
Merge branch 'develop' into feature/docs-cli
hjoaquim May 14, 2024
6f0c522
cli color
hjoaquim May 14, 2024
ca7f878
results in the global commands
hjoaquim May 14, 2024
d00476d
increase codeBlock line-height
montezdesousa May 14, 2024
65b9e0c
remove platform warning, obb is a class
montezdesousa May 14, 2024
f54c850
minor change, danger warning
montezdesousa May 14, 2024
fb5151f
typo?
montezdesousa May 14, 2024
2d6c892
Data processing commands
montezdesousa May 14, 2024
0d4101a
Merge branch 'develop' into feature/docs-cli
hjoaquim May 14, 2024
09cbf81
Merge branch 'develop' into feature/docs-cli
deeleeramone May 14, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading