From ab20b64d679fc784659591126e36e0445443a920 Mon Sep 17 00:00:00 2001 From: b-long Date: Thu, 18 Dec 2025 10:28:30 -0500 Subject: [PATCH 1/6] Create INSTALL.md file --- INSTALL.md | 245 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..6def3df1 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,245 @@ +# 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 (e.g., `C:\Program Files\otdfctl`) + +3. **Add to PATH:** + - Press `Windows key` and search for "Environment Variables" + - Click "Edit the system environment variables" + - Click "Environment Variables..." button + - Under "System variables", find and select "Path", then click "Edit..." + - Click "New" and add the folder where you extracted `otdfctl.exe` (e.g., `C:\Program Files\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 auth login` + +--- + +## 🔄 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 From d40e1206b67c1ef081168b4fb83246b8d5147b59 Mon Sep 17 00:00:00 2001 From: b-long Date: Fri, 19 Dec 2025 10:12:12 -0500 Subject: [PATCH 2/6] release-please integration --- .github/release-please/release-please-config.main.json | 4 ++++ .../release-please-config.release_branches.json | 4 ++++ 2 files changed, 8 insertions(+) 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" } ] } From 00186ec470ea9cdddd07aedc16e8af5b2e33ccc0 Mon Sep 17 00:00:00 2001 From: b-long Date: Fri, 19 Dec 2025 10:13:47 -0500 Subject: [PATCH 3/6] Update Windows section --- INSTALL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 6def3df1..67347409 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -168,14 +168,14 @@ Most Windows computers use `amd64`. ARM versions are for Surface Pro X or other 2. **Extract the ZIP file:** - Right-click the downloaded file - Select "Extract All..." - - Choose a location (e.g., `C:\Program Files\otdfctl`) + - 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 the system environment variables" - - Click "Environment Variables..." button - - Under "System variables", find and select "Path", then click "Edit..." - - Click "New" and add the folder where you extracted `otdfctl.exe` (e.g., `C:\Program Files\otdfctl`) + - 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. From 17bdc07b3f3debbe46d3cfd5f646bfff04576d53 Mon Sep 17 00:00:00 2001 From: b-long Date: Fri, 19 Dec 2025 11:23:28 -0500 Subject: [PATCH 4/6] Add "INSTALL.md" link from the primary README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) 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). From 2e25063445b27cb52627fca4e2b0bce42f65960a Mon Sep 17 00:00:00 2001 From: b-long Date: Fri, 19 Dec 2025 11:32:10 -0500 Subject: [PATCH 5/6] Collapse different OS blocks by default --- INSTALL.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 67347409..a7ab303c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -10,7 +10,8 @@ This guide will help you install **otdfctl** on your computer. Follow the steps ## 📥 Installation Instructions -### For macOS Users +
+

For macOS Users

 #### Step 1: Download the Right Version @@ -71,9 +72,12 @@ 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 +
+

For Linux Users

 #### Step 1: Download the Right Version @@ -151,9 +155,12 @@ sudo chmod +x /usr/local/bin/otdfctl rm otdfctl-0.28.0-linux-arm.tar.gz ``` +
+ --- -### For Windows Users +
+

For Windows Users

 #### Step 1: Download the Right Version @@ -180,6 +187,8 @@ Most Windows computers use `amd64`. ARM versions are for Surface Pro X or other 4. **Restart your command prompt or PowerShell** for the changes to take effect. +
+ --- ## ✅ Verify Installation From 6a3fc66392411d3db7351118b75c42596a0fd62a Mon Sep 17 00:00:00 2001 From: b-long Date: Fri, 19 Dec 2025 11:35:28 -0500 Subject: [PATCH 6/6] Update INSTALL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index a7ab303c..e043910b 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -243,7 +243,7 @@ sudo xattr -d com.apple.quarantine /usr/local/bin/otdfctl 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 auth login` +- Configure your first profile with `otdfctl profile create ` ---