Cli

Teledetection package Command Line Interface.

apikey(ctx, operation, argument)

Manage API keys.

 Other operations: list : List all available API keys

 Operations on locally-stored key: register : Register a new key remove : Remove a key provided in argument

 Manually input keys: create : Create a new API key revoke : Revoke a specific key revoke-all : Revoke all keys

Source code in teledetection/cli.py

@tld.command()
@click.argument(
    "operation",
    type=click.Choice(list(API_KEY_OPS.keys()), case_sensitive=False),
    required=False,
)
@click.argument("argument", default="")
@click.pass_context
def apikey(ctx, operation: str, argument: str):
    """Manage API keys.

    \b
    Other operations:
      list        : List all available API keys

    \b
    Operations on locally-stored key:
      register    : Register a new key
      remove      : Remove a key provided in argument

    \b
    Manually input keys:
      create      : Create a new API key
      revoke      : Revoke a specific key
      revoke-all  : Revoke all keys
    """
    if not operation:
        click.echo(ctx.get_help())
        ctx.exit(0)
    API_KEY_OPS[operation](argument)

collection_diff(stac_endpoint, col_path, remote_id='')

List collection items.

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option(
    "-p", "--col_path", type=str, help="Local collection path", required=True
)
@click.option(
    "-r",
    "--remote_id",
    type=str,
    help="Remote collection ID. If not specified, will use local collection ID",
    required=False,
)
def collection_diff(
    stac_endpoint: str,
    col_path: str,
    remote_id: str = "",
):
    """List collection items."""
    diff.compare_local_and_upstream(
        StacTransactionsHandler(stac_endpoint=stac_endpoint, sign=False),
        col_path,
        remote_id,
    )

delete(stac_endpoint, col_id, item_id)

Delete a STAC object (collection or item).

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option("-c", "--col_id", type=str, help="STAC collection ID", required=True)
@click.option("-i", "--item_id", type=str, default=None, help="STAC item ID")
def delete(
    stac_endpoint: str,
    col_id: str,
    item_id: str,
):
    """Delete a STAC object (collection or item)."""
    StacTransactionsHandler(
        stac_endpoint=stac_endpoint, sign=False
    ).delete_item_or_col(col_id=col_id, item_id=item_id)

do_create_key(description)

Create a new API key.

Source code in teledetection/cli.py

def do_create_key(description: str):
    """Create a new API key."""
    log.info("New API key %s created", _create_new_key(description=description))

do_list_keys()

List all generated API keys.

Source code in teledetection/cli.py

def do_list_keys():
    """List all generated API keys."""
    keys = _get_all_keys()
    if keys:
        log.info("All existing API keys:")
        log.info("Creation date      \tAccess key      \t[Description]")
        # Prints: 2025-05-06 09:22:50  zPL9GaQrokbMCQGe
        for key in keys:
            log.info(
                "%s\t%s\t%s",
                key["created"].split(".")[0],
                key["access-key"],
                key["description"],
            )
    else:
        log.info("No API key found.")

do_register_key(description)

Create and store a new API key.

Source code in teledetection/cli.py

def do_register_key(description: str):
    """Create and store a new API key."""
    new_key = _create_new_key(description=description)
    ApiKey.from_dict(new_key).to_config_dir()
    log.info("New API key %s created and stored in config directory", new_key)

do_remove_key(dont_revoke)

Delete the stored API key.

Source code in teledetection/cli.py

def do_remove_key(dont_revoke: bool):
    """Delete the stored API key."""
    if not dont_revoke:
        do_revoke_key(ApiKey.from_config_dir().access_key)
    ApiKey.delete_from_config_dir()

do_revoke_all_keys()

Revoke all API keys.

Source code in teledetection/cli.py

def do_revoke_all_keys():
    """Revoke all API keys."""
    keys = _get_all_keys()
    for key in keys:
        do_revoke_key(key["access-key"])
    if not keys:
        log.info("No API key to revoke.")

do_revoke_key(access_key)

Revoke an API key.

Source code in teledetection/cli.py

def do_revoke_key(access_key: str):
    """Revoke an API key."""
    _http(f"revoke_api_key?access_key={access_key}")
    log.info(f"API key {access_key} revoked")

do_sign_file(filepath)

Sign all URL in the provided file (modified in place).

Source code in teledetection/cli.py

def do_sign_file(filepath: str):
    """Sign all URL in the provided file (modified in place)."""
    update_hrefs_in_file(filepath=filepath)
    log.info("All URLs in file %s updated", filepath)

do_sign_qgz(filepath)

Sign all URLs in the provided QGIS project file (modified in place).

Source code in teledetection/cli.py

def do_sign_qgz(filepath: str):
    """Sign all URLs in the provided QGIS project file (modified in place)."""
    update_hrefs_in_qgz(filepath=filepath)
    log.info("All URLs in QGIS project %s updated", filepath)

do_sign_url(url)

Sign an URL.

Source code in teledetection/cli.py

def do_sign_url(url: str):
    """Sign an URL."""
    log.info("Signed url: %s", sign_string(url))

edit(stac_endpoint, col_id, item_id)

Edit a STAC object (collection, or item).

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option("-c", "--col_id", type=str, help="STAC collection ID", required=True)
@click.option("-i", "--item_id", type=str, default=None, help="STAC item ID")
def edit(stac_endpoint: str, col_id: str, item_id: str):
    """Edit a STAC object (collection, or item)."""
    with tempfile.NamedTemporaryFile(suffix=".json") as tf:
        StacTransactionsHandler(
            stac_endpoint=stac_endpoint, sign=False
        ).load_and_save(
            col_id=col_id, obj_pth=tf.name, item_id=item_id, pretty=True
        )
        editor = os.environ.get("EDITOR") or "vi"
        subprocess.run([editor, tf.name], check=False)
        StacTransactionsHandler(
            stac_endpoint=stac_endpoint, sign=False
        ).load_and_publish(obj_pth=tf.name)

grab(stac_endpoint, col_id, item_id, _sign, pretty, out_json)

Grab a STAC object (collection, or item) and save it as .json.

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option("-c", "--col_id", type=str, help="STAC collection ID", required=True)
@click.option("-i", "--item_id", type=str, default=None, help="STAC item ID")
@click.option(
    "-s", "--sign", "_sign", is_flag=True, default=False, help="Sign assets HREFs"
)
@click.option(
    "-p", "--pretty", is_flag=True, default=False, help="Pretty indent JSON"
)
@click.option("-o", "--out_json", type=str, help="Output .json file", required=True)
def grab(  # pylint: disable=too-many-arguments,too-many-positional-arguments
    stac_endpoint: str,
    col_id: str,
    item_id: str,
    _sign: bool,
    pretty: bool,
    out_json: str,
):
    """Grab a STAC object (collection, or item) and save it as .json."""
    StacTransactionsHandler(stac_endpoint=stac_endpoint, sign=_sign).load_and_save(
        col_id=col_id, obj_pth=out_json, item_id=item_id, pretty=pretty
    )

list_col_items(stac_endpoint, col_id, max_items, _sign)

List collection items.

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option("-c", "--col_id", type=str, help="STAC collection ID", required=True)
@click.option(
    "-m", "--max_items", type=int, help="Max number of items to display", default=20
)
@click.option(
    "-s", "--sign", "_sign", is_flag=True, default=False, help="Sign assets HREFs"
)
def list_col_items(stac_endpoint: str, col_id: str, max_items: int, _sign: bool):
    """List collection items."""
    items = StacTransactionsHandler(
        stac_endpoint=stac_endpoint, sign=_sign
    ).get_items(col_id=col_id, max_items=max_items)
    print(f"Found {len(items)} item(s):")
    for item in items:
        print(f"\t{item.id}")

list_cols(stac_endpoint)

List collections.

Source code in teledetection/cli.py

@tld.command()
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
def list_cols(
    stac_endpoint: str,
):
    """List collections."""
    cols = list(
        StacTransactionsHandler(
            stac_endpoint=stac_endpoint, sign=False
        ).client.get_collections()
    )
    print(f"Found {len(cols)} collection(s):")
    for col in sorted(cols, key=lambda x: x.id):
        print(f"\t{col.id}")

publish(stac_obj_path, stac_endpoint, storage_endpoint, storage_bucket, overwrite, keep_cog_dir)

Publish a STAC object (collection or item collection).

Source code in teledetection/cli.py

@tld.command()
@click.argument("stac_obj_path")
@click.option(
    "--stac_endpoint",
    help="Endpoint to which STAC objects will be sent",
    type=str,
    default=DEFAULT_STAC_EP,
)
@click.option(
    "--storage_endpoint",
    type=str,
    help="Storage endpoint assets will be sent to",
    default=DEFAULT_S3_EP,
)
@click.option(
    "-b",
    "--storage_bucket",
    help="Storage bucket assets will be sent to",
    type=str,
    default=DEFAULT_S3_STORAGE,
)
@click.option(
    "-o",
    "--overwrite",
    is_flag=True,
    default=False,
    help="Overwrite assets if already existing",
)
@click.option(
    "--keep_cog_dir",
    help="Set a directory to keep converted COG files",
    type=str,
    nargs=1,
    default="",
)
def publish(
    stac_obj_path: str,
    stac_endpoint: str,
    storage_endpoint: str,
    storage_bucket: str,
    overwrite: bool,
    keep_cog_dir: str,
):
    """Publish a STAC object (collection or item collection)."""
    StacUploadTransactionsHandler(
        stac_endpoint=stac_endpoint,
        sign=False,
        storage_endpoint=storage_endpoint,
        storage_bucket=storage_bucket,
        assets_overwrite=overwrite,
        keep_cog_dir=keep_cog_dir,
    ).load_and_publish(stac_obj_path)

sign(ctx, operation, argument)

Sign HREFs.

 Operations: url : Sign an URL file : Sign all URLs in the provided file (modified in place) qgis : Sign all URLs of a QGIS project file (modified in place)

Source code in teledetection/cli.py

@tld.command()
@click.argument(
    "operation",
    type=click.Choice(list(SIGN_KEY_OPS.keys()), case_sensitive=False),
    required=False,
)
@click.argument("argument")
@click.pass_context
def sign(ctx, operation: str, argument: str):
    """Sign HREFs.

    \b
    Operations:
      url         : Sign an URL
      file        : Sign all URLs in the provided file (modified in place)
      qgis        : Sign all URLs of a QGIS project file (modified in place)
    """
    if not operation:
        click.echo(ctx.get_help())
        ctx.exit(0)
    SIGN_KEY_OPS[operation](argument)

tld()

Teledetection Command Line Interface.

Source code in teledetection/cli.py

@click.group(
    help="Teledetection CLI",
    context_settings={
        "help_option_names": ["-h", "--help"],
        "max_content_width": 120,
    },
)
def tld() -> None:
    """Teledetection Command Line Interface."""