Skip to content

Commit 934ee29

Browse files
jmthomasjmthomas
authored
Merge pull request #1962 from OpenC3/cli
Document CLI
2 parents fe1da82 + a36548e commit 934ee29

File tree

102 files changed

+385
-140
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

102 files changed

+385
-140
lines changed

‎docs.openc3.com/docs/getting-started/cli.md

+237
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
---
2+
sidebar_position: 5
3+
title: Command Line Interface
4+
description: Using openc3.sh
5+
sidebar_custom_props:
6+
myEmoji: ⌨️
7+
---
8+
9+
The COSMOS Command Line Interface is `openc3.sh` and `openc3.bat` which are included in the COSMOS [project](https://github.com/OpenC3/cosmos-project) (more about [projects](key-concepts#projects)).
10+
11+
If you followed the [Installation Guide](installation.md) you should already be inside a cloned [openc3-project](https://github.com/OpenC3/cosmos-project) which is in your PATH (necessary for openc3.bat / openc3.sh to be resolved). To see all the available type the following:
12+
13+
```bash
14+
% openc3.sh cli
15+
Usage:
16+
cli help # Displays this information
17+
cli rake # Runs rake in the local directory
18+
cli irb # Runs irb in the local directory
19+
cli script list /PATH SCOPE # lists script names filtered by path within scope, 'DEFAULT' if not given
20+
cli script spawn NAME SCOPE variable1=value1 variable2=value2 # Starts named script remotely
21+
cli script run NAME SCOPE variable1=value1 variable2=value2 # Starts named script, monitoring status on console, by default until error or exit
22+
PARAMETERS name-value pairs to form the script's runtime environment
23+
OPTIONS: --wait 0 seconds to monitor status before detaching from the running script; ie --wait 100
24+
--disconnect run the script in disconnect mode
25+
cli validate /PATH/FILENAME.gem SCOPE variables.txt # Validate a COSMOS plugin gem file
26+
cli load /PATH/FILENAME.gem SCOPE variables.txt # Loads a COSMOS plugin gem file
27+
cli list <SCOPE> # Lists installed plugins, SCOPE is DEFAULT if not given
28+
cli generate TYPE OPTIONS # Generate various COSMOS entities
29+
OPTIONS: --ruby or --python is required to specify the language in the generated code unless OPENC3_LANGUAGE is set
30+
cli bridge CONFIG_FILENAME # Run COSMOS host bridge
31+
cli bridgegem gem_name variable1=value1 variable2=value2 # Runs bridge using gem bridge.txt
32+
cli bridgesetup CONFIG_FILENAME # Create a default config file
33+
cli pkginstall PKGFILENAME SCOPE # Install loaded package (Ruby gem or python package)
34+
cli pkguninstall PKGFILENAME SCOPE # Uninstall loaded package (Ruby gem or python package)
35+
cli rubysloc # DEPRECATED: Please use scc (https://github.com/boyter/scc)
36+
cli xtce_converter # Convert to and from the XTCE format. Run with --help for more info.
37+
cli cstol_converter # Converts CSTOL files (.prc) to COSMOS. Run with --help for more info.
38+
```
39+
40+
:::note seccomp profile
41+
You can safely ignore `WARNING: daemon is not using the default seccomp profile`
42+
:::
43+
44+
## Rake
45+
46+
You can execute rake tasks using `openc3.sh cli rake`. The most typical usage is to generate a plugin and then build it. For example:
47+
48+
```bash
49+
% openc3.sh cli rake build VERSION=1.0.0
50+
```
51+
52+
## IRB
53+
54+
IRB stands for Interactive Ruby and is a way to start a Ruby interpreter that you can play around with. When using it from the CLI, it includes the COSMOS Ruby path so you can `require 'cosmos'` and try out various methods. For example:
55+
56+
```bash
57+
% openc3.sh cli irb
58+
irb(main):001:0> require 'cosmos'
59+
=> true
60+
irb(main):002:0> Cosmos::Api::WHITELIST
61+
=>
62+
["get_interface",
63+
"get_interface_names",
64+
...
65+
]
66+
```
67+
68+
## Script
69+
70+
The script methods allow you to list the available scripts, spawn a script, and run a script while monitoring its output. Note that you must set the OPENC3_API_PASSWORD in Open Source and both the OPENC3_API_USER and OPENC3_API_PASSWORD in Enterprise.
71+
72+
:::note Offline Access Token
73+
You must visit the frontend Script Runner page as the OPENC3_API_USER in order to obtain an offline access token before the script cli methods will work.
74+
:::
75+
76+
### List
77+
78+
List all the available scripts which includes all the files in every target directory. You can filter this list using bash to only include procedures, Ruby files, Python files, etc.
79+
80+
```bash
81+
% export OPENC3_API_USER=operator
82+
% export OPENC3_API_PASSWORD=operator
83+
% openc3.sh cli script list
84+
EXAMPLE/cmd_tlm/example_cmds.txt
85+
EXAMPLE/cmd_tlm/example_tlm.txt
86+
...
87+
```
88+
89+
### Spawn
90+
91+
The ID of the spawned script is returned. You can connect to it in Script Runner by visiting `http://localhost:2900/tools/scriptrunner/1` where the final value is the ID.
92+
93+
```bash
94+
% openc3.sh spawn INST/procedures/checks.rb
95+
1
96+
```
97+
98+
### Run
99+
100+
Run spawns the script and then captures the output and prints it to the shell. Note that this will not work with user input prompts so the script must be written to prevent user input. You can also pass variables to the script as shown in the CLI help.
101+
102+
```bash
103+
% openc3.sh cli script run INST/procedures/stash.rb
104+
Filename INST/procedures/stash.rb scope DEFAULT
105+
2025/03/22 19:50:40.429 (SCRIPTRUNNER): Script config/DEFAULT/targets/INST/procedures/stash.rb spawned in 0.796683293 seconds <ruby 3.2.6>
106+
2025/03/22 19:50:40.453 (SCRIPTRUNNER): Starting script: stash.rb, line_delay = 0.1
107+
At [INST/procedures/stash.rb:3] state [running]
108+
At [INST/procedures/stash.rb:4] state [running]
109+
2025/03/22 19:50:40.732 (stash.rb:4): key1: val1
110+
At [INST/procedures/stash.rb:5] state [running]
111+
At [INST/procedures/stash.rb:6] state [running]
112+
2025/03/22 19:50:40.936 (stash.rb:6): key2: val2
113+
At [INST/procedures/stash.rb:7] state [running]
114+
2025/03/22 19:50:41.039 (stash.rb:7): CHECK: 'val1' == 'val1' is TRUE
115+
At [INST/procedures/stash.rb:8] state [running]
116+
2025/03/22 19:50:41.146 (stash.rb:8): CHECK: 'val2' == 'val2' is TRUE
117+
At [INST/procedures/stash.rb:9] state [running]
118+
2025/03/22 19:50:41.256 (stash.rb:9): CHECK: '["key1", "key2"]' == '["key1", "key2"]' is TRUE
119+
At [INST/procedures/stash.rb:10] state [running]
120+
At [INST/procedures/stash.rb:11] state [running]
121+
At [INST/procedures/stash.rb:12] state [running]
122+
2025/03/22 19:50:41.556 (stash.rb:12): CHECK: '{"key1"=>1, "key2"=>2}' == '{"key1"=>1, "key2"=>2}' is TRUE
123+
At [INST/procedures/stash.rb:13] state [running]
124+
At [INST/procedures/stash.rb:14] state [running]
125+
2025/03/22 19:50:41.763 (stash.rb:14): CHECK: true == true is TRUE
126+
At [INST/procedures/stash.rb:15] state [running]
127+
At [INST/procedures/stash.rb:16] state [running]
128+
At [INST/procedures/stash.rb:17] state [running]
129+
At [INST/procedures/stash.rb:18] state [running]
130+
2025/03/22 19:50:42.176 (stash.rb:18): CHECK: '[1, 2, [3, 4]]' == '[1, 2, [3, 4]]' is TRUE
131+
At [INST/procedures/stash.rb:19] state [running]
132+
At [INST/procedures/stash.rb:21] state [running]
133+
At [INST/procedures/stash.rb:22] state [running]
134+
At [INST/procedures/stash.rb:23] state [running]
135+
2025/03/22 19:50:42.587 (stash.rb:23): CHECK: '{"one"=>1, "two"=>2, "string"=>"string"}' == '{"one"=>1, "two"=>2, "string"=>"string"}' is TRUE
136+
At [INST/procedures/stash.rb:24] state [running]
137+
2025/03/22 19:50:42.697 (SCRIPTRUNNER): Script completed: stash.rb
138+
At [INST/procedures/stash.rb:0] state [stopped]
139+
script complete
140+
%
141+
```
142+
143+
## Validate
144+
145+
Validate is used to validate built COSMOS plugins. It walks through the installation process without actually installing the plugin.
146+
147+
```bash
148+
% openc3.sh cli validate openc3-cosmos-cfdp-1.0.0.gem
149+
Installing openc3-cosmos-cfdp-1.0.0.gem
150+
Successfully validated openc3-cosmos-cfdp-1.0.0.gem
151+
```
152+
153+
## Load
154+
155+
Load can load a plugin into COSMOS without using the GUI. This is useful for scripts or CI/CD pipelines.
156+
157+
```bash
158+
% openc3.sh cli load openc3-cosmos-cfdp-1.0.0.gem
159+
Loading new plugin: openc3-cosmos-cfdp-1.0.0.gem
160+
{"name"=>"openc3-cosmos-cfdp-1.0.0.gem", "variables"=>{"cfdp_microservice_name"=>"CFDP", "cfdp_route_prefix"=>"/cfdp", "cfdp_port"=>"2905", "cfdp_cmd_target_name"=>"CFDP2", "cfdp_cmd_packet_name"=>"CFDP_PDU", "cfdp_cmd_item_name"=>"PDU", "cfdp_tlm_target_name"=>"CFDP2", "cfdp_tlm_packet_name"=>"CFDP_PDU", "cfdp_tlm_item_name"=>"PDU", "source_entity_id"=>"1", "destination_entity_id"=>"2", "root_path"=>"/DEFAULT/targets_modified/CFDP/tmp", "bucket"=>"config", "plugin_test_mode"=>"false"}, "plugin_txt_lines"=>["VARIABLE cfdp_microservice_name CFDP", "VARIABLE cfdp_route_prefix /cfdp", "VARIABLE cfdp_port 2905", "", "VARIABLE cfdp_cmd_target_name CFDP2", "VARIABLE cfdp_cmd_packet_name CFDP_PDU", "VARIABLE cfdp_cmd_item_name PDU", "", "VARIABLE cfdp_tlm_target_name CFDP2", "VARIABLE cfdp_tlm_packet_name CFDP_PDU", "VARIABLE cfdp_tlm_item_name PDU", "", "VARIABLE source_entity_id 1", "VARIABLE destination_entity_id 2", "VARIABLE root_path /DEFAULT/targets_modified/CFDP/tmp", "VARIABLE bucket config", "", "# Set to true to enable a test configuration", "VARIABLE plugin_test_mode \"false\"", "", "MICROSERVICE CFDP <%= cfdp_microservice_name %>", " WORK_DIR .", " ROUTE_PREFIX <%= cfdp_route_prefix %>", " ENV OPENC3_ROUTE_PREFIX <%= cfdp_route_prefix %>", " ENV SECRET_KEY_BASE 324973597349867207430793759437697498769349867349674", " PORT <%= cfdp_port %>", " CMD rails s -b 0.0.0.0 -p <%= cfdp_port %> -e production", " # MIB Options Follow -", " # You will need to modify these for your mission", " OPTION source_entity_id <%= source_entity_id %>", " OPTION tlm_info <%= cfdp_tlm_target_name %> <%= cfdp_tlm_packet_name %> <%= cfdp_tlm_item_name %>", " OPTION destination_entity_id <%= destination_entity_id %>", " OPTION cmd_info <%= cfdp_cmd_target_name %> <%= cfdp_cmd_packet_name %> <%= cfdp_cmd_item_name %>", " OPTION root_path <%= root_path %>", " <% if bucket.to_s.strip != '' %>", " OPTION bucket <%= bucket %>", " <% end %>", "", "<% include_test = (plugin_test_mode.to_s.strip.downcase == \"true\") %>", "<% if include_test %>", " TARGET CFDPTEST CFDP", " TARGET CFDPTEST CFDP2", "", " MICROSERVICE CFDP CFDP2", " WORK_DIR .", " ROUTE_PREFIX /cfdp2", " ENV OPENC3_ROUTE_PREFIX /cfdp2", " ENV SECRET_KEY_BASE 324973597349867207430793759437697498769349867349674", " PORT 2906", " CMD rails s -b 0.0.0.0 -p 2906 -e production", " OPTION source_entity_id <%= destination_entity_id %>", " OPTION tlm_info CFDP CFDP_PDU PDU", " OPTION destination_entity_id <%= source_entity_id %>", " OPTION cmd_info CFDP CFDP_PDU PDU", " OPTION root_path <%= root_path %>", " <% if bucket.to_s.strip != '' %>", " OPTION bucket <%= bucket %>", " <% end %>", "", " <% test_host = ENV['KUBERNETES_SERVICE_HOST'] ? (scope.to_s.downcase + \"-interface-cfdp2-int-service\") : \"openc3-operator\" %>", " INTERFACE CFDP_INT tcpip_client_interface.rb <%= test_host %> 2907 2907 10.0 nil LENGTH 0 32 4 1 BIG_ENDIAN 0 nil nil true", " MAP_TARGET CFDP", "", " INTERFACE CFDP2_INT tcpip_server_interface.rb 2907 2907 10.0 nil LENGTH 0 32 4 1 BIG_ENDIAN 0 nil nil true", " PORT 2907", " MAP_TARGET CFDP2", "<% end %>"], "needs_dependencies"=>false, "updated_at"=>nil}
161+
Updating local plugin files: /plugins/DEFAULT/openc3-cosmos-cfdp
162+
```
163+
164+
## List
165+
166+
List displays all the installed plugins.
167+
168+
```bash
169+
% openc3.sh cli list
170+
openc3-cosmos-cfdp-1.0.0.gem__20250325160956
171+
openc3-cosmos-demo-6.2.2.pre.beta0.20250325143120.gem__20250325160201
172+
openc3-cosmos-enterprise-tool-admin-6.2.2.pre.beta0.20250325155648.gem__20250325160159
173+
openc3-cosmos-tool-autonomic-6.2.2.pre.beta0.20250325155658.gem__20250325160225
174+
openc3-cosmos-tool-bucketexplorer-6.2.2.pre.beta0.20250325143107.gem__20250325160227
175+
openc3-cosmos-tool-calendar-6.2.2.pre.beta0.20250325155654.gem__20250325160224
176+
openc3-cosmos-tool-cmdhistory-6.2.2.pre.beta0.20250325155651.gem__20250325160212
177+
openc3-cosmos-tool-cmdsender-6.2.2.pre.beta0.20250325143111.gem__20250325160211
178+
openc3-cosmos-tool-cmdtlmserver-6.2.2.pre.beta0.20250325143114.gem__20250325160208
179+
openc3-cosmos-tool-dataextractor-6.2.2.pre.beta0.20250325143104.gem__20250325160219
180+
openc3-cosmos-tool-dataviewer-6.2.2.pre.beta0.20250325143108.gem__20250325160220
181+
openc3-cosmos-tool-docs-6.2.2.pre.beta0.20250325155535.gem__20250325160228
182+
openc3-cosmos-tool-grafana-6.2.2.pre.beta0.20250325155658.gem__20250325160233
183+
openc3-cosmos-tool-handbooks-6.2.2.pre.beta0.20250325143113.gem__20250325160222
184+
openc3-cosmos-tool-iframe-6.2.2.pre.beta0.20250325143110.gem__20250325160158
185+
openc3-cosmos-tool-limitsmonitor-6.2.2.pre.beta0.20250325155448.gem__20250325160209
186+
openc3-cosmos-tool-packetviewer-6.2.2.pre.beta0.20250325143104.gem__20250325160215
187+
openc3-cosmos-tool-scriptrunner-6.2.2.pre.beta0.20250325143111.gem__20250325160214
188+
openc3-cosmos-tool-tablemanager-6.2.2.pre.beta0.20250325143116.gem__20250325160223
189+
openc3-cosmos-tool-tlmgrapher-6.2.2.pre.beta0.20250325143105.gem__20250325160218
190+
openc3-cosmos-tool-tlmviewer-6.2.2.pre.beta0.20250325143108.gem__20250325160216
191+
openc3-enterprise-tool-base-6.2.2.pre.beta0.20250325155704.gem__20250325160153
192+
```
193+
194+
## Generate
195+
196+
Generate is used to scaffold new COSMOS plugins, targets, conversions, and more! See the [Generators](/docs/getting-started/generators) page for more information.
197+
198+
## Bridge
199+
200+
A COSMOS Bridge is a small application that is run on the local computer to connect to hardware not available to Docker containers. A good example is connecting to a serial port on a non-linux system. See the
201+
[Bridge Guide](/docs/guides/bridges) for more information.
202+
203+
## Pkginstall and pkguninstall
204+
205+
Allows you to install or remove Ruby gems or Python wheels into COSMOS. These are dependencies that are not packaged with the COSMOS plugin itself.
206+
207+
```bash
208+
% openc3.sh cli pkginstall rspec-3.13.0.gem
209+
```
210+
211+
## Rubysloc (deprecated)
212+
213+
Calculates the Ruby Source Lines of Code (SLOC) from the current directory recursively. We recommend using [scc](https://github.com/boyter/scc) as it works across any programming language, calculates many more statistics, and is blazing fast.
214+
215+
## XTCE Converter
216+
217+
Converts from the XTCE format to the COSMOS format and also exports XTCE files given a COSMOS plugin.
218+
219+
```bash
220+
% openc3.sh cli xtce_converter
221+
Usage: xtce_converter [options] --import input_xtce_filename --output output_dir
222+
xtce_converter [options] --plugin /PATH/FILENAME.gem --output output_dir --variables variables.txt
223+
224+
-h, --help Show this message
225+
-i, --import VALUE Import the specified .xtce file
226+
-o, --output DIRECTORY Create files in the directory
227+
-p, --plugin PLUGIN Export .xtce file(s) from the plugin
228+
-v, --variables Optional variables file to pass to the plugin
229+
```
230+
231+
## CSTOL Converter
232+
233+
Converts from the Colorado System Test and Operations Language (CSTOL) to a COSMOS Script Runner Ruby script. It currently does not support conversion to Python. Simply run it in the same directory as CSTOL files (\*.prc) and it will convert them all.
234+
235+
```bash
236+
% openc3.sh cli cstol_converter
237+
```

‎docs.openc3.com/docs/getting-started/generators.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 6
33
title: Code Generators
44
description: Using openc3.sh to generate code
55
sidebar_custom_props:
66
myEmoji: 🏭
77
---
88

9-
The COSMOS Code Generators are built into the scripts `openc3.sh` and `openc3.bat` that are included in the COSMOS [project](https://github.com/OpenC3/cosmos-project) (more about [projects](key_concepts#projects)).
9+
The COSMOS Code Generators are built into the scripts `openc3.sh` and `openc3.bat` that are included in the COSMOS [project](https://github.com/OpenC3/cosmos-project) (more about [projects](key-concepts#projects)).
1010

1111
If you followed the [Installation Guide](installation.md) you should already be inside a cloned [openc3-project](https://github.com/OpenC3/cosmos-project) which is in your PATH (necessary for openc3.bat / openc3.sh to be resolved). To see all the available code generators type the following:
1212

‎docs.openc3.com/docs/getting-started/gettingstarted.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 3
33
title: Getting Started
44
description: Getting starting with COSMOS
55
sidebar_custom_props:

‎docs.openc3.com/docs/getting-started/installation.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 2
33
title: Installation
44
description: Installing OpenC3 COSMOS
55
sidebar_custom_props:
@@ -35,7 +35,7 @@ Docker by default will break idle (no data) connections after a period of 5 minu
3535

3636
### CLONE PROJECT
3737

38-
We recommend using the COSMOS [project template](key_concepts#projects) to get started.
38+
We recommend using the COSMOS [project template](key-concepts#projects) to get started.
3939

4040
```bash
4141
git clone https://github.com/OpenC3/cosmos-project.git

‎docs.openc3.com/docs/getting-started/key_concepts.md renamed to ‎docs.openc3.com/docs/getting-started/key-concepts.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 1
33
title: Key Concepts
44
description: Projects, Containerization, Frontend, Backend
55
sidebar_custom_props:
@@ -76,7 +76,7 @@ Per [AstroUXDS](https://www.astrouxds.com/), "The Astro Space UX Design System e
7676

7777
### Redis
7878

79-
[Redis](https://redis.io/) is an in-memory data store with support for strings, hashes, lists, sets, sorted sets, streams, and more. COSMOS uses Redis to store both our configuration and data. If you look back at our [container list](/docs/getting-started/key_concepts#containers) you'll notice two redis containers: cosmos-openc3-redis-1 and cosmos-openc3-redis-ephemeral-1. The ephemeral container contains all the real-time data pushed into [Redis streams](https://redis.io/docs/data-types/streams/). The other redis container contains COSMOS configuration that is meant to persist. [COSMOS Enterprise](https://openc3.com/enterprise) provides helm charts that setup [Redis Cluster](https://redis.io/docs/management/scaling/) to perform horizontal scaling where data is shared across multiple Redis nodes.
79+
[Redis](https://redis.io/) is an in-memory data store with support for strings, hashes, lists, sets, sorted sets, streams, and more. COSMOS uses Redis to store both our configuration and data. If you look back at our [container list](/docs/getting-started/key-concepts#containers) you'll notice two redis containers: cosmos-openc3-redis-1 and cosmos-openc3-redis-ephemeral-1. The ephemeral container contains all the real-time data pushed into [Redis streams](https://redis.io/docs/data-types/streams/). The other redis container contains COSMOS configuration that is meant to persist. [COSMOS Enterprise](https://openc3.com/enterprise) provides helm charts that setup [Redis Cluster](https://redis.io/docs/management/scaling/) to perform horizontal scaling where data is shared across multiple Redis nodes.
8080

8181
### MinIO
8282

‎docs.openc3.com/docs/getting-started/requirements.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 8
33
title: Requirements and Design
44
description: COSMOS Requirements and Design
55
sidebar_custom_props:

‎docs.openc3.com/docs/getting-started/upgrading.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -274,7 +274,7 @@ COSMOS 5 is a new architecture and treats targets as independent [plugins](../co
274274

275275
### Configuration Migration Tool
276276

277-
COSMOS 5 includes a migration tool for converting an existing COSMOS 4 configuration into a COSMOS 5 plugin. This example assumes an existing COSMOS 4 configuration at C:\COSMOS and a new COSMOS 5 installation at C:\cosmos-project. Linux users can adjust paths and change from .bat to .sh to follow along.
277+
COSMOS 5 (but not COSMOS 6) includes a migration tool for converting an existing COSMOS 4 configuration into a COSMOS 5 plugin. This example assumes an existing COSMOS 4 configuration at C:\COSMOS and a new COSMOS 5 installation at C:\cosmos-project. Linux users can adjust paths and change from .bat to .sh to follow along.
278278

279279
1. Change to the existing COSMOS 4 configuration directory. You should see the config, lib, procedures, outputs directory. You can then run the migration tool by specifying the absolute path to the COSMOS 5 installation.
280280

0 commit comments

Comments
 (0)