diff --git a/.github/release-please/release-please-config.main.json b/.github/release-please/release-please-config.main.json index a198f090..7d4a2fd5 100644 --- a/.github/release-please/release-please-config.main.json +++ b/.github/release-please/release-please-config.main.json @@ -11,6 +11,10 @@ { "type": "generic", "path": "pkg/config/config.go" + }, + { + "type": "generic", + "path": "INSTALL.md" } ] } diff --git a/.github/release-please/release-please-config.release_branches.json b/.github/release-please/release-please-config.release_branches.json index 94689a29..b1811085 100644 --- a/.github/release-please/release-please-config.release_branches.json +++ b/.github/release-please/release-please-config.release_branches.json @@ -10,6 +10,10 @@ { "type": "generic", "path": "pkg/config/config.go" + }, + { + "type": "generic", + "path": "INSTALL.md" } ] } diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..e043910b --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,254 @@ +# Installing otdfctl + +This guide will help you install **otdfctl** on your computer. Follow the steps for your operating system. + +## What is otdfctl? + +`otdfctl` is a command-line tool for working with OpenTDF. Once installed, you'll be able to run it from any folder on your computer. + +--- + +## 📥 Installation Instructions + +
+

For macOS Users

 + +#### Step 1: Download the Right Version + +First, you need to know which type of Mac you have: +- **Apple Silicon (M1, M2, M3, etc.)**: Download the `arm64` version +- **Intel Mac**: Download the `amd64` version + +**Don't know which one you have?** Open Terminal and type: +```bash +uname -m +``` +- If it says `arm64`, you have Apple Silicon +- If it says `x86_64`, you have an Intel Mac + +#### Step 2: Download and Install + +**For Apple Silicon Macs (M1/M2/M3):** +```bash +# Download the latest version +curl -LO https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-darwin-arm64.tar.gz + +# Extract the file +tar -xzf otdfctl-0.28.0-darwin-arm64.tar.gz + +# Create the directory if it doesn't exist +sudo mkdir -p /usr/local/bin + +# Move it to a folder in your PATH +sudo mv target/otdfctl-0.28.0-darwin-arm64 /usr/local/bin/otdfctl + +# Make it executable +sudo chmod +x /usr/local/bin/otdfctl + +# Clean up the downloaded file +rm otdfctl-0.28.0-darwin-arm64.tar.gz +``` + +**For Intel Macs:** +```bash +# Download the latest version +curl -LO https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-darwin-amd64.tar.gz + +# Extract the file +tar -xzf otdfctl-0.28.0-darwin-amd64.tar.gz + +# Create the directory if it doesn't exist +sudo mkdir -p /usr/local/bin + +# Move it to a folder in your PATH +sudo mv target/otdfctl-0.28.0-darwin-amd64 /usr/local/bin/otdfctl + +# Make it executable +sudo chmod +x /usr/local/bin/otdfctl + +# Clean up the downloaded file +rm otdfctl-0.28.0-darwin-amd64.tar.gz +``` + +> **Note:** You'll be asked for your password when using `sudo`. This is normal and required to install the tool. + +
+ +--- + +
+

For Linux Users

 + +#### Step 1: Download the Right Version + +Choose based on your system: +- **Most modern PCs**: `amd64` +- **Raspberry Pi or ARM devices**: `arm64` or `arm` + +**Not sure?** Run this command: +```bash +uname -m +``` + +#### Step 2: Download and Install + +**For amd64 (most common):** +```bash +# Download the latest version +curl -LO https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-linux-amd64.tar.gz + +# Extract the file +tar -xzf otdfctl-0.28.0-linux-amd64.tar.gz + +# Create the directory if it doesn't exist +sudo mkdir -p /usr/local/bin + +# Move it to a folder in your PATH +sudo mv target/otdfctl-0.28.0-linux-amd64 /usr/local/bin/otdfctl + +# Make it executable +sudo chmod +x /usr/local/bin/otdfctl + +# Clean up the downloaded file +rm otdfctl-0.28.0-linux-amd64.tar.gz +``` + +**For ARM64:** +```bash +# Download the latest version +curl -LO https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-linux-arm64.tar.gz + +# Extract the file +tar -xzf otdfctl-0.28.0-linux-arm64.tar.gz + +# Create the directory if it doesn't exist +sudo mkdir -p /usr/local/bin + +# Move it to a folder in your PATH +sudo mv target/otdfctl-0.28.0-linux-arm64 /usr/local/bin/otdfctl + +# Make it executable +sudo chmod +x /usr/local/bin/otdfctl + +# Clean up the downloaded file +rm otdfctl-0.28.0-linux-arm64.tar.gz +``` + +**For ARM (32-bit):** +```bash +# Download the latest version +curl -LO https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-linux-arm.tar.gz + +# Extract the file +tar -xzf otdfctl-0.28.0-linux-arm.tar.gz + +# Create the directory if it doesn't exist +sudo mkdir -p /usr/local/bin + +# Move it to a folder in your PATH +sudo mv target/otdfctl-0.28.0-linux-arm /usr/local/bin/otdfctl + +# Make it executable +sudo chmod +x /usr/local/bin/otdfctl + +# Clean up the downloaded file +rm otdfctl-0.28.0-linux-arm.tar.gz +``` + +
+ +--- + +
+

For Windows Users

 + +#### Step 1: Download the Right Version + +Most Windows computers use `amd64`. ARM versions are for Surface Pro X or other ARM-based Windows devices. + +#### Step 2: Download and Install + +1. **Download the file** for your system: + - For most PCs: [otdfctl-0.28.0-windows-amd64.zip](https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-windows-amd64.zip) + - For ARM devices: [otdfctl-0.28.0-windows-arm64.zip](https://github.com/opentdf/otdfctl/releases/download/v0.28.0/otdfctl-0.28.0-windows-arm64.zip) + +2. **Extract the ZIP file:** + - Right-click the downloaded file + - Select "Extract All..." + - Choose a location and create a folder: `%USERPROFILE%\otdfctl` + - The executable will be in this folder (you may need to navigate into a subfolder) + +3. **Add to PATH:** + - Press `Windows key` and search for "Environment Variables" + - Click "Edit environment variables for your account" + - In the "User variables" section at the top, find and select "Path", then click "Edit...". (If "Path" doesn't exist, click "New..." to create it). + - Click "New" and add the folder path where you extracted `otdfctl.exe` (e.g., `%USERPROFILE%\otdfctl`) + - Click "OK" on all windows + +4. **Restart your command prompt or PowerShell** for the changes to take effect. + +
+ +--- + +## ✅ Verify Installation + +After installation, open a **new** terminal window and run: + +```bash +otdfctl --version +``` + +You should see output like: +``` +otdfctl version 0.28.0 +``` + +If you see this, congratulations! 🎉 You've successfully installed otdfctl. + +--- + +## 🔧 Troubleshooting + +### "command not found" or "otdfctl is not recognized" + +**On macOS/Linux:** +- Make sure you opened a **new** terminal window after installation +- Verify the file is in `/usr/local/bin/` by running: `ls -l /usr/local/bin/otdfctl` +- Check if `/usr/local/bin` is in your PATH: `echo $PATH` + +**On Windows:** +- Make sure you opened a **new** Command Prompt or PowerShell window +- Verify the PATH was added correctly in Environment Variables +- Try searching for `otdfctl.exe` in File Explorer to confirm where it's located + +### "Permission denied" on macOS/Linux + +If you get a permission error, make sure the file is executable: +```bash +sudo chmod +x /usr/local/bin/otdfctl +``` + +### macOS: "otdfctl cannot be opened because the developer cannot be verified" + +This is a security feature on macOS. To allow it: +```bash +sudo xattr -d com.apple.quarantine /usr/local/bin/otdfctl +``` + +--- + +## 📚 Next Steps + +Now that otdfctl is installed, you can: +- Run `otdfctl --help` to see available commands +- Visit the [documentation](https://github.com/opentdf/otdfctl) for usage examples +- Configure your first profile with `otdfctl profile create ` + +--- + +## 🔄 Updating otdfctl + +To update to a newer version, simply repeat the installation steps with the new version number. The new version will replace the old one. + +To check for new releases, visit: https://github.com/opentdf/otdfctl/releases diff --git a/README.md b/README.md index 15e3c0d5..e40bda1c 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ The main goals are to: ## Usage +See [INSTALL.md](INSTALL.md) for installation instructions. + The CLI is configured via profiles. Use `otdfctl profile create ` (and optionally `--set-default`) to define how the CLI should connect to your platform instance. Load up the platform (see its [README](https://github.com/opentdf/platform?tab=readme-ov-file#run) for instructions).