flist_cli_v/README.md

125 lines
3.2 KiB
Markdown
Raw Normal View History

<h1> Flist CLI in Vlang </h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Building and Installing](#building-and-installing)
2024-10-02 16:36:57 +00:00
- [Rebuild and Uninstall](#rebuild-and-uninstall)
- [Usage](#usage)
2024-10-02 16:41:08 +00:00
- [Commands](#commands)
- [OS-Specific Instructions](#os-specific-instructions)
2024-10-03 07:01:05 +00:00
- [Linux](#linux)
- [macOS](#macos)
- [Windows](#windows)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
---
## Introduction
Flist CLI is a tool that turns Dockerfiles and Docker images directly into Flist on the TF Flist Hub, passing through Docker Hub.
## Installation
### Prerequisites
- [V programming language](https://vlang.io/) (latest version) installed on your system
- Docker installed and running
- Docker Hub account
- TF Hub account and token
### Building and Installing
2024-10-02 16:41:08 +00:00
Clone this repository, build the project, and install the CLI:
```
git clone https://git.ourworld.tf/tfgrid/flist_cli_v
cd flist_cli_v
make build
```
2024-10-02 16:41:08 +00:00
This will build the `flist` executable and install it to the appropriate system location.
2024-10-02 16:36:57 +00:00
### Rebuild and Uninstall
2024-10-02 16:23:41 +00:00
2024-10-02 16:36:57 +00:00
You can use the following Makefile commands:
2024-10-02 16:23:41 +00:00
2024-10-02 16:36:57 +00:00
- To rebuild and reinstall:
```
make rebuild
```
- To uninstall and remove the binary:
```
make delete
```
2024-10-02 16:23:41 +00:00
## Usage
After installation, you can use the `flist` command followed by various subcommands:
```
flist <command> [arguments]
```
2024-10-02 16:41:08 +00:00
## Commands
- `install`: Install the Flist CLI
- `uninstall`: Uninstall the Flist CLI
- `login`: Log in to Docker Hub and save the Flist Hub token
- `logout`: Log out of Docker Hub and remove the Flist Hub token
- `push <image>:<tag>`: Build and push a Docker image, then convert and push it as an flist
- `delete <flist_name>`: Delete an flist from Flist Hub
- `rename <flist_name> <new_flist_name>`: Rename an flist in Flist Hub
2024-10-02 16:41:08 +00:00
- `ls`: List all flists of the current user
- `ls url`: List all flists of the current user with full URLs
- `help`: Display help information
## OS-Specific Instructions
2024-10-03 07:01:05 +00:00
### Linux
2024-10-03 07:01:05 +00:00
1. Ensure Docker is installed and the Docker daemon is running.
2. The `flist` executable will be installed to:
```
2024-10-03 07:01:05 +00:00
/usr/local/bin/flist
```
2024-10-03 07:01:05 +00:00
### macOS
2024-10-03 07:01:05 +00:00
1. Ensure Docker Desktop is installed and running.
2. The `flist` executable will be installed to:
```
/usr/local/bin/flist
```
2024-10-03 07:01:05 +00:00
### Windows
For now, we recommend to use WSL and follow the Linux steps.
## Troubleshooting
- If you encounter permission issues, ensure you're running the command with appropriate privileges (e.g., as administrator on Windows or with `sudo` on Unix-like systems).
- Make sure Docker is running before using Flist CLI commands.
- If you face issues with Docker commands, try logging out and logging back in to refresh your Docker credentials.
- If you encounter compilation errors, ensure you have the latest version of V installed.
## Development
To modify the Flist CLI:
1. Make your changes to the `flist.v` file.
2024-10-02 16:36:57 +00:00
2. Rebuild the project using `make rebuild`
3. Test your changes thoroughly across different operating systems if possible.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
[Apache 2.0 License](LICENSE)