Module: cli

Script containing a command line interface to upload and download repositories from/to arweave. This file is a thin wrapper around RepoManager & FileManager classes to facilitate usage of the repo upload and download functions from the command line.

This CLI is commonly used to upload and download model files from/to arweave, similar to how models are handled in huggingface hub.

download_file(file_path, tx_id, gateways=DEFAULT_GATEWAYS, show_progress=True)

Downloads a file from Arweave using the transaction ID.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the file to download.	required
tx_id	str	Transaction ID of the file to download.	required
gateways	str	Comma separated list of Arweave gateways.	DEFAULT_GATEWAYS
show_progress	bool	If set to false, it will not show the progress bar while	True

To download a file with transaction id to the path :

ritual-arweave download-file --file-path --tx-id

Source code in src/ritual_arweave/cli.py

@click.option(
    "--file-path",
    type=str,
    help="Path to the file to download",
)
@click.option(
    "--tx-id",
    type=str,
    help="Transaction id of the file to download",
)
@show_progress_option
@gateways_option
@cli.command(
    name="download-file",
)
def download_file(
    file_path: str,
    tx_id: str,
    gateways: str = DEFAULT_GATEWAYS,
    show_progress: bool = True,
) -> None:
    """
    Downloads a file from Arweave using the transaction ID.

    Parameters:
        file_path: Path to the file to download.
        tx_id: Transaction ID of the file to download.
        gateways: Comma separated list of Arweave gateways.
        show_progress: If set to false, it will not show the progress bar while

    Examples:

    To download a file with transaction id <tx-id> to the path <file-path>:

    ritual-arweave download-file --file-path <file-path> --tx-id <tx-id>
    """
    fm = FileManager(gateways=gateways.split(","), show_progress_bar=show_progress)
    fm.download(file_path, tx_id)

download_repo(repo_id, base_path='.', force_download=False, show_progress=True, gateways=DEFAULT_GATEWAYS)

Downloads a repo from Arweave using the specified repo ID, and API URL. Optionally, you can specify multiple owners and a base path where the repo files will be saved. Use the --force-download flag to override existing files.

Parameters:

Name	Type	Description	Default
repo_id	str	The ID of the repository to download.	required
base_path	str	The base path to save the repo files. Defaults to the current directory.	'.'
force_download	bool	If set, it will override the existing repo files if they exist.	False
show_progress	bool	If set, it will show progress bar while downloading files.	True
gateways	str	Commas separated list of Arweave gateways.	DEFAULT_GATEWAYS

To download a repo with ID and owner :

ritual-arweave download-repo --repo-id --owner

To download a repo with ID and owner and save the repo files to :

ritual-arweave download-repo --repo-id --base-path

Source code in src/ritual_arweave/cli.py

@click.option(
    "--base-path",
    type=str,
    default=".",
    required=False,
    help="enter base path to save repo files, defaults to the current directory.",
)
@click.option(
    "--force-download",
    is_flag=True,
    default=False,
    required=False,
    help="If set, it will override the existing repo files if they exist",
)
@repo_id_option
@show_progress_option
@gateways_option
@cli.command(
    name="download-repo",
)
def download_repo(
    repo_id: str,
    base_path: str = ".",
    force_download: bool = False,
    show_progress: bool = True,
    gateways: str = DEFAULT_GATEWAYS,
) -> None:
    """
    Downloads a repo from Arweave using the specified repo ID, and
    API URL. Optionally, you can specify multiple owners and a
    base path where the repo files will be saved.
    Use the --force-download flag to override existing files.

    Parameters:
        repo_id: The ID of the repository to download.
        base_path: The base path to save the repo files. Defaults to the current
            directory.
        force_download: If set, it will override the existing repo files if they exist.
        show_progress: If set, it will show progress bar while downloading files.
        gateways: Commas separated list of Arweave gateways.

    Examples:

    To download a repo with ID <repo-id> and owner <owner-address>:

    ritual-arweave download-repo --repo-id <repo-id> --owner <owner-address>

    To download a repo with ID <repo-id> and owner <owner-address> and save the repo
    files to <path-to-save-repo>:

    ritual-arweave download-repo --repo-id <repo-id> --base-path <path-to-save-repo>
    """

    try:
        files = RepoManager(
            gateways=gateways.split(","), show_progress_bar=show_progress
        ).download_repo(
            repo_id,
            base_path,
            force_download,
        )
    except NotFinalizedException:
        click.echo(
            f"Repo with ID {repo_id} is not finalized yet. Please retry "
            f"in a few minutes."
        )
        return

    click.echo(f"downloaded files: {files}")

upload_file(file_path, max_upload_size, show_progress=True, gateways=','.join(DEFAULT_GATEWAYS), wallet='wallet.json', tags='{}')

Uploads a file to Arweave.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the file to upload.	required
max_upload_size	int	For large files, the file will be split into chunks of this	required
gateways	str	Comma separated list of Arweave gateways.	join(DEFAULT_GATEWAYS)
wallet	str	Path to the wallet file. Default is wallet.json.	'wallet.json'
tags	str	Dictionary of tags to attach to the file. Must be a JSON string.	'{}'

To upload a file with path :

ritual-arweave upload-file --file-path

Source code in src/ritual_arweave/cli.py

@click.option(
    "--file-path",
    type=str,
    help="Path to the file to upload",
    required=True,
)
@click.option(
    "--tags",
    type=str,
    required=False,
    default="{}",
    help="Dictionary of tags to attach to the file. Must be a JSON string.",
)
@max_upload_size_option
@show_progress_option
@gateways_option
@wallet_option
@cli.command(
    name="upload-file",
)
def upload_file(
    file_path: str,
    max_upload_size: int,
    show_progress: bool = True,
    gateways: str = ",".join(DEFAULT_GATEWAYS),
    wallet: str = "wallet.json",
    tags: str = "{}",
) -> None:
    """
    Uploads a file to Arweave.

    Parameters:
        file_path: Path to the file to upload.
        max_upload_size: For large files, the file will be split into chunks of this
        size.
        gateways: Comma separated list of Arweave gateways.
        wallet: Path to the wallet file. Default is `wallet.json`.
        tags: Dictionary of tags to attach to the file. Must be a JSON string.

    Examples:

    To upload a file with path <file-path>:

    ritual-arweave upload-file --file-path <file-path>
    """
    fm = FileManager(
        gateways=gateways.split(","),
        wallet_path=wallet,
        max_upload_size=max_upload_size,
        show_progress_bar=show_progress,
    )
    tx = fm.upload(Path(file_path), tags_dict=json.loads(tags))
    click.echo(f"uploaded file: {tx.id}")

upload_repo(repo_name, repo_dir, version_file, wallet, show_progress, gateways)

Uploads a repo to Arweave using the specified repo name & repo directory.

Parameters:

Name	Type	Description	Default
repo_name	str	Name of the repo to upload.	required
repo_dir	str	Path to the repo directory.	required
version_file	optional	Path to the version mapping file. This is a json file that maps repo filenames to their corresponding versions.	required
wallet	optional	Path to the wallet file. Default is wallet.json.	required
show_progress	bool	If set, it will show progress bar while uploading files.	required
gateways	optional	Commas separated list of Arweave gateways.	required

To upload a repo with ID from the directory :

ritual-arweave upload-repo --repo-name --repo-dir

To upload a repo with ID from the directory and version mapping file :

ritual-arweave upload-repo --repo-name --repo-dir --version-file

To upload a repo with ID from the directory and wallet :

ritual-arweave upload-repo --repo-name --repo-dir --wallet

Source code in src/ritual_arweave/cli.py

@click.option(
    "--repo-dir",
    required=True,
    type=click.Path(exists=True, readable=True),
    help="Enter repo directory",
)
@click.option(
    "--version-file",
    required=False,
    default=None,
    type=str,
    help="enter version mapping json of repo files to upload",
)
@repo_name_option
@wallet_option
@show_progress_option
@gateways_option
@cli.command(
    name="upload-repo",
)
def upload_repo(
    repo_name: str,
    repo_dir: str,
    version_file: Optional[str],
    wallet: str,
    show_progress: bool,
    gateways: str,
) -> None:
    """
    Uploads a repo to Arweave using the specified repo name & repo directory.

    Parameters:
        repo_name: Name of the repo to upload.
        repo_dir: Path to the repo directory.
        version_file (optional): Path to the version mapping file. This is a json file
            that maps repo filenames to their corresponding versions.
        wallet (optional): Path to the wallet file. Default is `wallet.json`.
        show_progress: If set, it will show progress bar while uploading files.
        gateways (optional): Commas separated list of Arweave gateways.


    Examples:

    To upload a repo with ID <repo-id> from the directory <repo-dir>:

    ritual-arweave upload-repo --repo-name <repo-name> --repo-dir <repo-dir>

    To upload a repo with ID <repo-id> from the directory <repo-dir> and version
    mapping file <version-file>:

    ritual-arweave upload-repo --repo-name <repo-name> --repo-dir <repo-dir> \
        --version-file <version-file>

    To upload a repo with ID <repo-id> from the directory <repo-dir> and
    wallet <wallet>:

    ritual-arweave upload-repo --repo-name <repo-name> --repo-dir <repo-dir> \
        --wallet <wallet>

    """
    r = RepoManager(
        gateways=gateways.split(","),
        wallet_path=wallet,
        show_progress_bar=show_progress,
    ).upload_repo(name=repo_name, path=repo_dir, version_mapping_file=version_file)
    click.echo(
        f"uploaded repo: {r}"
        f"\n\tyou can download it using the repo id: "
        f"`{r.repo_id.owner}/{r.repo_id.name}`"
    )