Getting Started - CLI#

Invoking the CLI#

If you have installed the SDK using pip, the Satcat CLI should already be installed in your path. You can verify this using:

$ satcat version
satcat version 1.0.0

One-Line Screening#

Most Satcat operational on-demand screening workflows begin with uploading an ephemeris file propagated from an owner/operator orbit determination solution. This ephemeris can be any one of the formats supported by Satcat, and may contain any number of maneuvers. To retrieve the list of supported ephemeris file formats from the server, you can use list_ephemeris_formats or the CLI satcat list ephemeris-formats.

Warning

If your ephemeris contains maneuvers, they should be indicated explicitly by whatever mechanism the ephemeris format provides for specifying discontinuities. For example, the CCSDS OEM format dictates that separate “blocks” are separated by discontinuities. This prevents interpolation from taking place over maneuvers, which is critical to the accuracy of screening.

With the Satcat CLI, you can upload an ephemeris file and submit a screening with a single command:

satcat create screening --pid 25544 --pef MEME_25544_ISS_Ephemeris_2022181_OEM.txt --pfmt oem --wait

Let’s review the parameters being used:

--pid, short for “primary ID”, is the NORAD Catalog ID of the object which the uploaded ephemeris file describes.

--pef, short for “primary ephemeris file”, is the path to the ephemeris file being uploaded.

--pfmt, short for “primary ephemeris format”, is the file format of the ephemeris file being uploaded.

Note

You must specify both the file format of the ephemeris as well as the NORAD Catalog ID of the object that the ephemeris describes while uploading the file. This information helps us parse your file, and prevents us from screening the data in your file against the catalog data for the same object.

--wait indicates that the operation should block until the screening has been processed on Satcat servers and wait to exit until the screening is completed.

You may also choose to instead use the --submit flag, which will submit the screening to be processed and return immediately. In this case, the screening can then be awaited subsequently using satcat await screening.

Take note of the id field of the created screening - this ID is used to retrieve the results of the screening once it is complete.

Retrieving Results#

Once a screening is complete, you can retrieve the resulting conjunctions using satcat list conjunctions:

satcat list conjunctions [screening_id]

Listing Entities#

You can use the satcat list command to list any entity in the Satcat screening API, including your screenings:

$ satcat list screenings

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Id                                   ┃ Title     ┃ Status  ┃ Created At                ┃ Conjunctions Count ┃ Primary Ids Preview ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ dd44f906-1e9c-40cd-b97f-e6d791b39b96 │ Screening │ SUCCESS │ 2022-06-22 14:50:24+00:00 │ 12                 │ [25544]             │
└──────────────────────────────────────┴───────────┴─────────┴───────────────────────────┴────────────────────┴─────────────────────┘

Note

In the Screening list table with rich formatting, the values in the Id column are automatic hyperlinks to the Satcat web application on supported terminal clients (ctrl-click / cmd-click to open in your web browser). Since Satcat screenings all run on Satcat servers, you can view the same screening results and information on the Satcat website easily after configuring and running them using the SDK or CLI.

Output Formatting#

By default, the Satcat CLI uses rich output formatting including tables and progress indicators for human readability. However, you can also configure the CLI to output plain JSON data for machine readability or redirecting to a file (e.g. for logging purposes).

To set the output format to json, use the --output-format (-o) flag of the satcat base command:

satcat --output-format json ...

Note

The --output-format flag must be specified after the base satcat command but before any subcommands. For example, the following would be invalid:

satcat list screenings --output-format json

To disable interactive progress indicators in the terminal output, you can use the --no-progress flag of the satcat base command:

satcat --no-progress ...

These settings can also be persistently configured in the settings module (see Configuration) as settings.output_format and settings.show_progress respectively.

Note

The default rich CLI output format only displays a curated subset of information for each resource type for maximum readability. To view all fields of a resource and inspect in detail, it’s best to use --output-format json.

Downloading an Ephemeris#

You can also download the content of an ephemeris file on the Satcat servers. This includes:

  • Owner/Operator ephemerides that you have uploaded or have access to

  • Ephemerides created during propagation using the Satcat propagation features

  • Ephemerides from any catalogs to which you have access

To download an ephemeris, all you need is its unique identifier (id) and the file format in which you want the ephemeris to be downloaded. Then, you can use satcat download ephemeris to download the file content.

Note

Currently, only the OEM and NASA formats are supported for ephemeris file downloads (case insensitive).

For example, to upload an ephemeris file and download it in another format:

# Upload an OEM ephemeris to Satcat
satcat create ephemeris MEME_25544_OEM_EPH.txt oem 25544

# The above command will show the metadata of the uploaded file,
# including an "id" field containing the ephemeris's new unique id.

# To download it in another format (in this case, the NASA format):

satcat download ephemeris ${EPHEMERIS_ID_FROM_UPLOAD} -o MEME_25544_NASA_EPH.txt -f nasa

# Where EPHEMERIS_ID_FROM_UPLOAD is the unique identifier of the
# ephemeris uploaded using the previous command.

# Here is an example of how the command would look after substituting the id:

satcat download ephemeris 0608a3fa-5005-421e-lmeu-4a168932562f \
    -o MEME_25544_NASA_EPH.txt -f nasa

This downloads the ephemeris using the desired format (specified using the -f flag) and saves the downloaded file to the requested output path (specified using the -o flag).

Note

If the -o (--output-file) flag is not specified, the content of the file is printed to stdout (terminal output).