2024-10-02 05:19:16 +00:00
< 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-11 07:23:47 +00:00
- [Rebuilding and Uninstalling ](#rebuilding-and-uninstalling )
- [Available Commands ](#available-commands )
2024-10-02 05:19:16 +00:00
- [Usage ](#usage )
- [OS-Specific Instructions ](#os-specific-instructions )
2024-10-03 07:01:05 +00:00
- [Linux ](#linux )
- [macOS ](#macos )
2024-10-02 05:19:16 +00:00
- [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
2024-10-11 15:59:23 +00:00
- [Docker Engine ](https://docs.docker.com/engine/install/ ) installed and running (Linux)
- [Docker Desktop ](https://www.docker.com/products/docker-desktop/ ) installed and running (MacOS+Windows)
- [Docker Hub ](https://hub.docker.com/ ) account
- [TF Hub ](https://hub.grid.tf/ ) account and token
Read more on the TF Hub and Flist on the ThreeFold Manual [here ](https://manual.grid.tf/documentation/developers/flist/flist.html ).
2024-10-02 05:19:16 +00:00
### Building and Installing
2024-10-10 14:42:44 +00:00
- To clone this repository, build the project, and install the CLI:
- MacOS and Linux
```
git clone https://git.ourworld.tf/tfgrid/flist_cli_v
cd flist_cli_v
make build
```
- Windows
```
git clone https://git.ourworld.tf/tfgrid/flist_cli_v
cd flist_cli_v
make build-win
```
This will build the executable and install it to the appropriate system location.
2024-10-02 05:19:16 +00:00
2024-10-11 07:23:47 +00:00
### Rebuilding and Uninstalling
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:
2024-10-10 14:42:44 +00:00
- MacOS and Linux
```
make rebuild
```
- Windows
```
make rebuild-win
```
2024-10-02 16:36:57 +00:00
- To uninstall and remove the binary:
2024-10-10 14:42:44 +00:00
- MacOS and Linux
```
make delete
```
- Windows
```
make delete-win
```
2024-10-02 16:23:41 +00:00
2024-10-11 07:23:47 +00:00
## Available Commands
2024-10-02 05:19:16 +00:00
After installation, you can use the `flist` command followed by various subcommands:
```
flist < command > [arguments]
```
2024-10-10 14:42:44 +00:00
Run `flist` or `flist help` to see all available commands for your specific OS.
2024-10-02 05:19:16 +00:00
2024-10-11 07:23:47 +00:00
- `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` - Build and push a Docker image to Docker Hub, then convert and push it as an Flist to Flist Hub
- `delete` - Delete an Flist from Flist Hub
- `rename` - Rename an Flist in Flist Hub
- `ls` - List all Flists of the current user
- `ls url` - List all Flists of the current user with full URLs
- `help` - Display this help message
## Usage
A Linux user would use the following commands:
```
sudo ./flist install
sudo flist uninstall
flist login
flist logout
flist push < image > :< tag >
flist delete < flist_name >
flist rename < flist_name > < new_flist_name >
flist ls
flist ls url
flist help
```
2024-10-02 05:19:16 +00:00
## OS-Specific Instructions
2024-10-03 07:01:05 +00:00
### Linux
2024-10-02 05:19:16 +00:00
2024-10-10 14:42:44 +00:00
1. Ensure Docker Engine is installed and running.
2024-10-03 07:01:05 +00:00
2. The `flist` executable will be installed to:
2024-10-02 05:19:16 +00:00
```
2024-10-03 07:01:05 +00:00
/usr/local/bin/flist
2024-10-02 05:19:16 +00:00
```
2024-10-03 07:01:05 +00:00
### macOS
2024-10-02 05:19:16 +00:00
2024-10-03 07:01:05 +00:00
1. Ensure Docker Desktop is installed and running.
2024-10-02 05:19:16 +00:00
2. The `flist` executable will be installed to:
```
/usr/local/bin/flist
```
2024-10-03 07:01:05 +00:00
### Windows
2024-10-10 14:42:44 +00:00
1. Ensure Docker Desktop is installed and running.
2. Run the program and installer in an admin PowerShell.
3. The `flist.exe` executable will be installed to:
```
C:\\Program Files\\flist\\flist.exe
```
2024-10-03 07:01:05 +00:00
2024-10-02 05:19:16 +00:00
## 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).
- If you face issues with Docker commands, try logging out and logging back in to refresh your Docker credentials.
2024-10-10 14:42:44 +00:00
- If you encounter compilation errors, ensure you have the latest version of V installed. To update v, run `v up` .
2024-10-02 05:19:16 +00:00
## Development
To modify the Flist CLI:
1. Make your changes to the `flist.v` file.
2024-10-10 14:42:44 +00:00
2. Rebuild the project using using the appropriate Make command.
2024-10-02 05:19:16 +00:00
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 )