From 9b89ce1498f66011a9548e1c98cd16fd389ae007 Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Sun, 21 Dec 2025 08:40:25 +0100 Subject: [PATCH 1/7] docs: add GitOps deployments documentation - Add comprehensive GitOps documentation for pipeops.yaml manifest - Document manifest reference (build, deploy, env, resources, autoscale, network) - Explain sync policies (manual, auto, webhook) - Document custom K8s manifest support for BYOC clusters - Add best practices and troubleshooting guides --- docs/projects/gitops.md | 320 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 docs/projects/gitops.md diff --git a/docs/projects/gitops.md b/docs/projects/gitops.md new file mode 100644 index 0000000..8849ee4 --- /dev/null +++ b/docs/projects/gitops.md @@ -0,0 +1,320 @@ +--- +sidebar_position: 14 +title: GitOps Deployments +description: Deploy applications using GitOps principles with declarative configuration +--- + +# GitOps Deployments + +GitOps is a declarative approach to infrastructure and application deployment where the desired state of your system is defined in a Git repository. PipeOps GitOps enables you to manage your deployments using a `pipeops.yaml` manifest file, similar to ArgoCD. + +## Overview + +With GitOps enabled, PipeOps: + +- **Watches your repository** for changes to the manifest file +- **Automatically syncs** your deployment to match the desired state +- **Detects drift** between git and live state +- **Provides visibility** into sync status and history + +## Quick Start + +### 1. Create a pipeops.yaml File + +Add a `pipeops.yaml` file to the root of your repository: + +```yaml +apiVersion: pipeops.io/v1 +kind: Application +metadata: + name: my-app + labels: + team: backend + environment: production +spec: + build: + framework: nodejs + builder: nixpacks + dockerfile: Dockerfile + context: . + deploy: + replicas: 3 + strategy: rolling + env: + - name: NODE_ENV + value: production + - name: DATABASE_URL + valueFrom: doppler://production/DATABASE_URL + resources: + cpu: "500m" + memory: "512Mi" + autoscale: + enabled: true + minReplicas: 2 + maxReplicas: 10 + network: + port: 3000 + public: true + domains: + - app.example.com +``` + +### 2. Enable GitOps for Your Project + +When creating a new project, select **GitOps** as the project type: + +1. Navigate to **Projects** → **Create Project** +2. Select **GitOps** as the project type +3. Connect your repository +4. Configure the manifest path (default: `/pipeops.yaml`) +5. Set your sync policy + +### 3. Deploy + +Once configured, PipeOps will: +- Detect the `pipeops.yaml` in your repository +- Parse and validate the manifest +- Deploy your application according to the specification + +## Manifest Reference + +### Metadata + +```yaml +metadata: + name: my-app # Application name + labels: # Optional labels + team: backend + environment: production +``` + +### Build Configuration + +```yaml +spec: + build: + framework: nodejs # Framework: nodejs, python, go, etc. + builder: nixpacks # Builder: nixpacks, dockerfile, buildpack + dockerfile: Dockerfile # Dockerfile path (if using dockerfile builder) + context: . # Build context directory + args: # Build arguments + - NODE_ENV=production +``` + +### Deployment Configuration + +```yaml +spec: + deploy: + replicas: 3 # Number of replicas + strategy: rolling # Deployment strategy: rolling, recreate +``` + +### Environment Variables + +```yaml +spec: + env: + - name: NODE_ENV # Plain value + value: production + - name: DATABASE_URL # From Doppler + valueFrom: doppler://production/DATABASE_URL + - name: API_KEY # From secret + valueFrom: + secretRef: + name: api-secrets + key: api-key +``` + +### Resources + +```yaml +spec: + resources: + cpu: "500m" # CPU request/limit + memory: "512Mi" # Memory request/limit +``` + +### Autoscaling + +```yaml +spec: + autoscale: + enabled: true + minReplicas: 2 + maxReplicas: 10 + targetCPU: 80 # Target CPU utilization % +``` + +### Networking + +```yaml +spec: + network: + port: 3000 # Container port + public: true # Expose publicly + domains: # Custom domains + - app.example.com + - www.example.com +``` + +## Sync Policies + +| Policy | Description | +|--------|-------------| +| **Manual** | Sync only when explicitly triggered | +| **Auto** | Automatically sync on a schedule (every 5 minutes) | +| **Webhook** | Sync when git push webhook is received (recommended) | + +### Configuring Sync Policy + +In the project settings: + +1. Navigate to **Project Settings** → **GitOps** +2. Select your preferred sync policy +3. Enable additional options: + - **Auto Prune**: Delete resources removed from manifest + - **Self Heal**: Automatically correct drift from desired state + +## Sync Status + +| Status | Description | +|--------|-------------| +| **Synced** | Deployment matches git state | +| **OutOfSync** | Changes detected, sync needed | +| **Syncing** | Sync in progress | +| **Failed** | Sync failed - check logs | +| **Unknown** | Status not yet determined | + +## Viewing Diff + +Before syncing, you can preview changes: + +1. Navigate to your GitOps project +2. Click **View Diff** to see pending changes +3. Review added, modified, and removed configurations +4. Click **Sync** to apply changes + +## Custom Kubernetes Manifests (BYOC Only) + +For users with their own Kubernetes clusters (BYOC - Bring Your Own Cluster), PipeOps supports deploying raw Kubernetes manifests. + +:::warning Important +Custom Kubernetes manifests are **NOT allowed** on PipeOps managed clusters (PKS) for security and stability reasons. +::: + +### Cluster Type Support + +| Cluster Type | `pipeops` Manifest | `kubernetes` Manifest | +|--------------|-------------------|----------------------| +| PKS (PipeOps Managed) | ✅ Allowed | ❌ Not Allowed | +| AWS (User Account) | ✅ Allowed | ✅ Allowed | +| GCP (User Account) | ✅ Allowed | ✅ Allowed | +| Azure (User Account) | ✅ Allowed | ✅ Allowed | +| BYOC (Agent-managed) | ✅ Allowed | ✅ Allowed | + +### Using Custom K8s Manifests + +1. Create a directory with your Kubernetes YAML files: + +``` +your-repo/ +├── k8s/ +│ ├── deployment.yaml +│ ├── service.yaml +│ ├── configmap.yaml +│ └── ingress.yaml +└── README.md +``` + +2. When creating the GitOps project, set: + - **Manifest Type**: `kubernetes` + - **Manifest Path**: `/k8s` + +3. PipeOps will apply all YAML files in the specified directory + +### Supported Kubernetes Resources + +All standard Kubernetes resources are supported: + +- Deployments, StatefulSets, DaemonSets +- Services, Ingresses +- ConfigMaps, Secrets +- PersistentVolumeClaims +- CronJobs, Jobs +- ServiceAccounts, Roles, RoleBindings +- NetworkPolicies +- Custom Resource Definitions (CRDs) + +## Best Practices + +### 1. Use Environment-Specific Manifests + +Organize your manifests by environment: + +``` +your-repo/ +├── manifests/ +│ ├── base/ +│ │ └── pipeops.yaml +│ ├── staging/ +│ │ └── pipeops.yaml +│ └── production/ +│ └── pipeops.yaml +``` + +### 2. Version Your Manifests + +Use the `apiVersion` field to track manifest schema versions: + +```yaml +apiVersion: pipeops.io/v1 +``` + +### 3. Use Secrets Safely + +Never commit secrets directly. Use: + +- **Doppler integration**: `valueFrom: doppler://project/SECRET_NAME` +- **Secret references**: Reference secrets managed in PipeOps + +### 4. Enable Self-Heal for Production + +Enable self-heal to automatically correct any manual changes or drift: + +``` +Sync Policy: webhook +Auto Prune: true +Self Heal: true +``` + +### 5. Review Diffs Before Syncing + +Always review the diff before syncing to production to understand what changes will be applied. + +## Troubleshooting + +### Sync Failed + +1. Check the sync history for error messages +2. Validate your `pipeops.yaml` syntax +3. Ensure all referenced secrets exist +4. Check if the target cluster is accessible + +### Manifest Not Found + +1. Verify the manifest path is correct +2. Ensure the file is committed to the correct branch +3. Check file permissions in the repository + +### OutOfSync After Deploy + +1. Someone may have made manual changes +2. Enable **Self Heal** to auto-correct drift +3. Click **Sync** to reconcile + +## Related Documentation + +- [Project Deployment](./project-deployment.md) +- [Project Settings](./project-settings.md) +- [Environment Variables](/docs/Integrations/environment-variable) From dbcb17538fb5d913b15ecd0956f72c4fdbbb835e Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Sun, 21 Dec 2025 08:50:29 +0100 Subject: [PATCH 2/7] Update gitops.md --- docs/projects/gitops.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/projects/gitops.md b/docs/projects/gitops.md index 8849ee4..1b373b5 100644 --- a/docs/projects/gitops.md +++ b/docs/projects/gitops.md @@ -200,7 +200,7 @@ Before syncing, you can preview changes: For users with their own Kubernetes clusters (BYOC - Bring Your Own Cluster), PipeOps supports deploying raw Kubernetes manifests. :::warning Important -Custom Kubernetes manifests are **NOT allowed** on PipeOps managed clusters (PKS) for security and stability reasons. +Custom Kubernetes manifests are **NOT allowed** on PipeOps-managed clusters (PKS) for security and stability reasons. ::: ### Cluster Type Support From 2bf7a9a877308137b31a25a237907617114e1d20 Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Sun, 21 Dec 2025 08:58:16 +0100 Subject: [PATCH 3/7] fix: correct broken link to environment variables docs --- docs/projects/gitops.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/projects/gitops.md b/docs/projects/gitops.md index 1b373b5..8fb24a0 100644 --- a/docs/projects/gitops.md +++ b/docs/projects/gitops.md @@ -317,4 +317,4 @@ Always review the diff before syncing to production to understand what changes w - [Project Deployment](./project-deployment.md) - [Project Settings](./project-settings.md) -- [Environment Variables](/docs/Integrations/environment-variable) +- [Environment Variables](./project-settings.md#environment-variable) From ab13e97b8338b2aa3b61d15ba35fa0fb5624050c Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Thu, 16 Jul 2026 11:32:14 +0100 Subject: [PATCH 4/7] Document verified PipeOps CLI commands --- docs/pipeops-cli.md | 110 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 docs/pipeops-cli.md diff --git a/docs/pipeops-cli.md b/docs/pipeops-cli.md new file mode 100644 index 0000000..e43ad22 --- /dev/null +++ b/docs/pipeops-cli.md @@ -0,0 +1,110 @@ +--- +sidebar_position: 11 +slug: pipeops-cli +title: PipeOps CLI +--- + +# PipeOps CLI + +The PipeOps CLI lets you inspect PipeOps resources from your terminal. This page lists the commands that are currently verified for read/list workflows. + +For automation, prefer JSON output: + +```bash +pipeops --json +``` + +If your account has multiple workspaces, set the workspace explicitly before running workspace-scoped commands: + +```bash +export PIPEOPS_WORKSPACE_UUID= +``` + +You can get the workspace UUID from: + +```bash +pipeops workspace list --json +``` + +## Authentication + +```bash +pipeops login +pipeops status --json +pipeops me --json +``` + +Use `pipeops login` to authenticate through the browser. Use `status` and `me` to verify the active CLI session. + +## Workspaces + +```bash +pipeops workspace list --json +pipeops workspace get --json +``` + +`workspace list` returns the workspaces available to your account. `workspace get` returns details for one workspace. + +## Projects + +```bash +pipeops project list --json +pipeops list --json +pipeops project get --json +pipeops project deployments --json +pipeops project deployment-history --json +``` + +`pipeops list` is a top-level shortcut for listing projects. + +## Add-ons + +Use `pipeops addons` to list add-ons that can be deployed from the PipeOps catalog: + +```bash +pipeops addons --json +pipeops addons available --json +pipeops addons catalog --json +pipeops addons categories --json +pipeops addons info --json +``` + +Use `pipeops addons list` to list add-ons already deployed in your current workspace: + +```bash +pipeops addons list --json +pipeops addons ls --json +pipeops addons deployments --json +pipeops addons deployment get --json +``` + +## Servers + +```bash +pipeops server list --json +pipeops server status --json +``` + +These commands return the servers available in the current workspace and details for a single server. + +## Removed placeholder commands + +The following placeholder commands are not currently available in the CLI: + +```bash +pipeops connect +pipeops proxy +pipeops exec +pipeops shell +``` + +## Commands pending API or SDK support + +The following read commands are intentionally not listed as working commands yet because they currently depend on API or SDK follow-up work: + +- `pipeops environment list --json` +- `pipeops project env get --json` +- `pipeops token list --json` +- `pipeops server connection --json` +- `pipeops server cost --json` + From 1c3f35912a78967a2b19e4b36753fda95e461a8a Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Thu, 16 Jul 2026 11:53:04 +0100 Subject: [PATCH 5/7] Update PipeOps CLI command docs --- docs/pipeops-cli.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/pipeops-cli.md b/docs/pipeops-cli.md index e43ad22..33c557c 100644 --- a/docs/pipeops-cli.md +++ b/docs/pipeops-cli.md @@ -51,11 +51,21 @@ pipeops workspace get --json pipeops project list --json pipeops list --json pipeops project get --json +pipeops project env get --json pipeops project deployments --json pipeops project deployment-history --json ``` -`pipeops list` is a top-level shortcut for listing projects. +`pipeops list` is a top-level shortcut for listing projects. `project env get` returns the project's environment variables as key/value pairs. + +## Environments + +```bash +pipeops environment list --json +pipeops environment get --json +``` + +`environment list` returns environments in the selected workspace. `environment get` returns one environment by UUID or ID. ## Add-ons @@ -83,9 +93,20 @@ pipeops addons deployment get --json ```bash pipeops server list --json pipeops server status --json +pipeops server connection --json +pipeops server cost --json +``` + +These commands return servers in the current workspace, server details, connection status, and cost allocation data. If OpenCost does not have allocation data yet, `server cost` returns a structured JSON response with `available: false`. + +## Service account tokens + +```bash +pipeops token list --json +pipeops token get --json ``` -These commands return the servers available in the current workspace and details for a single server. +These commands list service account tokens for the selected workspace and return details for a single token. ## Removed placeholder commands @@ -97,14 +118,3 @@ pipeops proxy pipeops exec pipeops shell ``` - -## Commands pending API or SDK support - -The following read commands are intentionally not listed as working commands yet because they currently depend on API or SDK follow-up work: - -- `pipeops environment list --json` -- `pipeops project env get --json` -- `pipeops token list --json` -- `pipeops server connection --json` -- `pipeops server cost --json` - From 7702b7f88e6ed7e2806412968c49b5297a782be3 Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Thu, 16 Jul 2026 12:02:30 +0100 Subject: [PATCH 6/7] Update CLI auth command docs --- docs/cli/advanced/cicd.md | 4 +- docs/cli/advanced/docker.md | 6 +- docs/cli/commands/authentication.md | 70 +++++++++++------------ docs/cli/commands/overview.md | 29 +++++----- docs/cli/getting-started/configuration.md | 12 ++-- docs/cli/getting-started/installation.md | 2 +- docs/cli/getting-started/quick-start.md | 8 +-- docs/cli/overview.md | 2 +- docs/cli/reference/troubleshooting.md | 20 +++---- 9 files changed, 76 insertions(+), 77 deletions(-) diff --git a/docs/cli/advanced/cicd.md b/docs/cli/advanced/cicd.md index 009f41c..f3a398f 100644 --- a/docs/cli/advanced/cicd.md +++ b/docs/cli/advanced/cicd.md @@ -356,7 +356,7 @@ Always handle errors gracefully: set -e # Check authentication -if ! pipeops auth status > /dev/null 2>&1; then +if ! pipeops status > /dev/null 2>&1; then echo "Authentication failed" exit 1 fi @@ -469,7 +469,7 @@ pipeops --version echo $PIPEOPS_AUTH_TOKEN | wc -c # Test authentication -pipeops auth status +pipeops status ``` #### JSON Parsing Errors diff --git a/docs/cli/advanced/docker.md b/docs/cli/advanced/docker.md index f79b070..8c0cc0d 100644 --- a/docs/cli/advanced/docker.md +++ b/docs/cli/advanced/docker.md @@ -35,7 +35,7 @@ To maintain authentication between container runs, mount the configuration direc ```bash docker run -it --rm \ -v ~/.pipeops:/root/.pipeops \ - pipeops/cli:latest auth login + pipeops/cli:latest login ``` ### Using Environment Variables @@ -59,7 +59,7 @@ alias pipeops='docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:late Usage: ```bash -pipeops auth login +pipeops login pipeops list pipeops status proj-123 ``` @@ -97,7 +97,7 @@ jobs: monitor: image: pipeops/cli:latest script: - - pipeops auth status + - pipeops status - pipeops list - pipeops status proj-123 variables: diff --git a/docs/cli/commands/authentication.md b/docs/cli/commands/authentication.md index 1534746..044423f 100644 --- a/docs/cli/commands/authentication.md +++ b/docs/cli/commands/authentication.md @@ -6,16 +6,16 @@ description: "Reference for PipeOps CLI authentication commands covering login w # Authentication Commands -The `pipeops auth` commands manage authentication and user account information. These commands handle login, logout, and session management for the PipeOps CLI. +The PipeOps CLI authentication commands manage login, logout, session status, and user account information. -## `pipeops auth login` +## `pipeops login` Authenticate with PipeOps using OAuth 2.0 with PKCE flow. ### Usage ```bash -pipeops auth login [flags] +pipeops login [flags] ``` ### Description @@ -33,12 +33,12 @@ Opens your default web browser to complete OAuth authentication. Once authentica **Standard login**: ```bash -pipeops auth login +pipeops login ``` **Login without opening browser**: ```bash -pipeops auth login --no-browser +pipeops login --no-browser ``` Output: @@ -73,13 +73,13 @@ The CLI uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authen **Browser doesn't open**: ```bash # Manually copy and open the URL -pipeops auth login --no-browser +pipeops login --no-browser ``` **Authentication timeout**: ```bash # Restart the process -pipeops auth login +pipeops login ``` **Permission denied**: @@ -90,19 +90,19 @@ chmod 600 ~/.pipeops.json --- -## `pipeops auth logout` +## `pipeops logout` Sign out and remove local credentials. ### Usage ```bash -pipeops auth logout [flags] +pipeops logout [flags] ``` ### Description -Removes the authentication token from local configuration. After logout, you'll need to run `pipeops auth login` again to use authenticated commands. +Removes the authentication token from local configuration. After logout, you'll need to run `pipeops login` again to use authenticated commands. ### Flags @@ -114,7 +114,7 @@ Removes the authentication token from local configuration. After logout, you'll **Standard logout**: ```bash -pipeops auth logout +pipeops logout ``` Output: @@ -125,7 +125,7 @@ Are you sure you want to logout? [y/N] y **Force logout without confirmation**: ```bash -pipeops auth logout --force +pipeops logout --force ``` ### What Gets Removed @@ -140,14 +140,14 @@ Logging out does **not** revoke the token on the server. To fully revoke access, --- -## `pipeops auth status` +## `pipeops status` Check current authentication status. ### Usage ```bash -pipeops auth status [flags] +pipeops status [flags] ``` ### Description @@ -158,7 +158,7 @@ Verifies if you're currently authenticated and displays session information. **Check auth status**: ```bash -pipeops auth status +pipeops status ``` Output when authenticated: @@ -170,12 +170,12 @@ Token expires: 2024-12-31 23:59:59 Output when not authenticated: ``` ✗ Not authenticated -Run 'pipeops auth login' to authenticate +Run 'pipeops login' to authenticate ``` **JSON output**: ```bash -pipeops auth status --json +pipeops status --json ``` ```json @@ -198,25 +198,25 @@ pipeops auth status --json ```bash # Check if authenticated before running commands -if pipeops auth status > /dev/null 2>&1; then +if pipeops status > /dev/null 2>&1; then echo "Authenticated, proceeding..." pipeops project list else echo "Not authenticated, please login" - pipeops auth login + pipeops login fi ``` --- -## `pipeops auth me` +## `pipeops me` Display current user information. ### Usage ```bash -pipeops auth me [flags] +pipeops me [flags] ``` ### Description @@ -227,7 +227,7 @@ Shows detailed information about the currently authenticated user. **View user info**: ```bash -pipeops auth me +pipeops me ``` Output: @@ -241,7 +241,7 @@ Account ID: usr_1234567890 **JSON output**: ```bash -pipeops auth me --json +pipeops me --json ``` ```json @@ -275,7 +275,7 @@ For CI/CD pipelines, use environment variables instead of interactive login: export PIPEOPS_AUTH_TOKEN=${{ secrets.PIPEOPS_TOKEN }} # Verify authentication -pipeops auth status +pipeops status # Run commands pipeops list @@ -288,10 +288,10 @@ Manage multiple PipeOps accounts using different config files: ```bash # Login to production account -PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops auth login +PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops login # Login to staging account -PIPEOPS_CONFIG_PATH=~/.pipeops-staging.json pipeops auth login +PIPEOPS_CONFIG_PATH=~/.pipeops-staging.json pipeops login # Use specific account alias pipeops-prod='PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops' @@ -319,8 +319,8 @@ Best practices for token management: 4. **Rotate tokens regularly**: ```bash - pipeops auth logout - pipeops auth login + pipeops logout + pipeops login ``` ### Headless Servers @@ -329,7 +329,7 @@ For servers without a browser: ```bash # On the headless server -pipeops auth login --no-browser +pipeops login --no-browser # Copy the URL and open it on your local machine # After authorization, the server CLI will authenticate automatically @@ -354,23 +354,23 @@ echo '{"auth_token":"your-token-here"}' > ~/.pipeops.json **"Not authenticated"**: ``` Error: not authenticated -Run 'pipeops auth login' to authenticate +Run 'pipeops login' to authenticate ``` -**Solution**: Run `pipeops auth login` +**Solution**: Run `pipeops login` **"Token expired"**: ``` Error: authentication token has expired -Run 'pipeops auth login' to re-authenticate +Run 'pipeops login' to re-authenticate ``` -**Solution**: Run `pipeops auth login` to refresh +**Solution**: Run `pipeops login` to refresh **"Invalid token"**: ``` Error: invalid authentication token -Run 'pipeops auth login' to re-authenticate +Run 'pipeops login' to re-authenticate ``` -**Solution**: Run `pipeops auth logout` then `pipeops auth login` +**Solution**: Run `pipeops logout` then `pipeops login` **"Permission denied"**: ``` diff --git a/docs/cli/commands/overview.md b/docs/cli/commands/overview.md index c314987..9f26479 100644 --- a/docs/cli/commands/overview.md +++ b/docs/cli/commands/overview.md @@ -17,7 +17,7 @@ pipeops [options] [flags] ### Examples ```bash -pipeops auth login +pipeops login pipeops list pipeops logs proj-123 --follow ``` @@ -29,7 +29,10 @@ pipeops logs proj-123 --follow Manage authentication and user accounts. ```bash -pipeops auth +pipeops login +pipeops logout +pipeops status +pipeops me ``` | Command | Description | @@ -150,7 +153,7 @@ Most commands support both interactive and non-interactive modes: **Interactive** (prompts for input): ```bash -pipeops auth login +pipeops login ``` **Non-Interactive** (all options via flags): @@ -231,7 +234,8 @@ Get help for any command: pipeops --help # Category help -pipeops auth --help +pipeops login --help +pipeops logout --help pipeops project --help # Specific command help @@ -242,28 +246,23 @@ pipeops logs --help ### Example Output ```bash -$ pipeops auth --help +$ pipeops login --help Authenticate with PipeOps Usage: - pipeops auth [flags] - -Available Commands: - login Authenticate with PipeOps using OAuth - logout Sign out and remove local credentials - status Check current authentication status - me Display current user information + pipeops login [flags] Flags: - -h, --help help for auth + --auth-url string OAuth2 authorization URL + -h, --help help for login Global Flags: --json Output in JSON format -v, --verbose Enable verbose output -q, --quiet Suppress non-essential output -Use "pipeops auth --help" for more information about a command. +Use "pipeops [command] --help" for more information about a command. ``` ## Command Aliases @@ -328,7 +327,7 @@ See [Configuration](/docs/cli/getting-started/configuration) for more details. set -e # Exit on error # Authenticate -pipeops auth status || pipeops auth login +pipeops status || pipeops login # List projects pipeops list diff --git a/docs/cli/getting-started/configuration.md b/docs/cli/getting-started/configuration.md index a572d17..2ecc449 100644 --- a/docs/cli/getting-started/configuration.md +++ b/docs/cli/getting-started/configuration.md @@ -33,7 +33,7 @@ The CLI stores its configuration in a JSON file located at: | Option | Description | Default | |--------|-------------|---------| | `api_url` | PipeOps API endpoint | `https://api.pipeops.io` | -| `auth_token` | Authentication token (set by `auth login`) | - | +| `auth_token` | Authentication token (set by `login`) | - | | `default_project` | Default project for commands | - | | `output_format` | Output format (`text`, `json`) | `text` | | `log_level` | Logging level (`debug`, `info`, `warn`, `error`) | `info` | @@ -63,7 +63,7 @@ Specify a custom location for the configuration file: ```bash export PIPEOPS_CONFIG_PATH=/path/to/custom/config.json -pipeops auth login +pipeops login ``` #### `PIPEOPS_API_URL` @@ -276,7 +276,7 @@ pipeops-staging status proj-123 ### Login Flow -When you run `pipeops auth login`, the CLI: +When you run `pipeops login`, the CLI: 1. Opens your browser for OAuth authentication 2. Receives an authorization code @@ -314,7 +314,7 @@ For CI/CD pipelines, use secrets management to store tokens securely. Tokens are automatically refreshed by the CLI. If authentication expires: ```bash -pipeops auth login +pipeops login ``` ## Project-Specific Configuration @@ -506,7 +506,7 @@ If the configuration file is corrupted: mv ~/.pipeops.json ~/.pipeops.json.backup # Create new configuration -pipeops auth login +pipeops login ``` ### Environment Variable Not Working @@ -529,7 +529,7 @@ To start fresh: ```bash rm ~/.pipeops.json -pipeops auth login +pipeops login ``` ## Next Steps diff --git a/docs/cli/getting-started/installation.md b/docs/cli/getting-started/installation.md index 98c1050..08159dc 100644 --- a/docs/cli/getting-started/installation.md +++ b/docs/cli/getting-started/installation.md @@ -141,7 +141,7 @@ docker pull pipeops/cli:latest docker run -it --rm pipeops/cli:latest --help # Run with persistent configuration -docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:latest auth login +docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:latest login ``` For convenience, create an alias: diff --git a/docs/cli/getting-started/quick-start.md b/docs/cli/getting-started/quick-start.md index 0c6bc6d..9f407fe 100644 --- a/docs/cli/getting-started/quick-start.md +++ b/docs/cli/getting-started/quick-start.md @@ -19,7 +19,7 @@ This guide will help you get up and running with the PipeOps CLI in minutes. You First, authenticate with your PipeOps account: ```bash -pipeops auth login +pipeops login ``` This will: @@ -39,13 +39,13 @@ Opening browser for authentication... Check your authentication status: ```bash -pipeops auth status +pipeops status ``` View your account information: ```bash -pipeops auth me +pipeops me ``` ## Step 2: Create Your First Project @@ -286,7 +286,7 @@ Here's a complete workflow from authentication to monitoring: ```bash # 1. Authenticate -pipeops auth login +pipeops login # 2. List your projects pipeops list diff --git a/docs/cli/overview.md b/docs/cli/overview.md index bde4298..5205e04 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -58,7 +58,7 @@ The PipeOps Command Line Interface (CLI) is a powerful tool that enables you to The PipeOps CLI organizes commands into logical categories: -- **Authentication** (`pipeops auth`) - Login, logout, and account management +- **Authentication** (`pipeops login`, `pipeops logout`, `pipeops status`, `pipeops me`) - Login, logout, and account management - **Projects** (`pipeops project`) - Project lifecycle management - **Monitoring** (`pipeops list`, `pipeops status`, `pipeops logs`) - View project and addon information - **Servers** (`pipeops server`) - Server provisioning and management diff --git a/docs/cli/reference/troubleshooting.md b/docs/cli/reference/troubleshooting.md index 2695517..c7f7113 100644 --- a/docs/cli/reference/troubleshooting.md +++ b/docs/cli/reference/troubleshooting.md @@ -73,7 +73,7 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash ### Authentication Failed -**Problem**: `pipeops auth login` fails. +**Problem**: `pipeops login` fails. **Solutions**: @@ -85,12 +85,12 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash 2. **Clear existing configuration**: ```bash rm ~/.pipeops.json - pipeops auth login + pipeops login ``` 3. **Use manual browser authentication**: ```bash - pipeops auth login --no-browser + pipeops login --no-browser # Copy and paste the URL into your browser ``` @@ -102,8 +102,8 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash ```bash # Re-authenticate -pipeops auth logout -pipeops auth login +pipeops logout +pipeops login ``` ### Invalid Token @@ -125,7 +125,7 @@ pipeops auth login 3. **Re-authenticate**: ```bash - pipeops auth login + pipeops login ``` --- @@ -262,7 +262,7 @@ pipeops auth login ```bash mv ~/.pipeops.json ~/.pipeops.json.backup echo '{}' > ~/.pipeops.json - pipeops auth login + pipeops login ``` ### Environment Variables Not Working @@ -525,7 +525,7 @@ For persistent issues: | Error | Cause | Solution | |-------|-------|----------| | `command not found: pipeops` | CLI not in PATH | Add to PATH or reinstall | -| `not authenticated` | No valid auth token | Run `pipeops auth login` | +| `not authenticated` | No valid auth token | Run `pipeops login` | | `token expired` | Auth token expired | Re-authenticate | | `project not found` | Invalid project name | Check project name with `project list` | | `permission denied` | Insufficient permissions | Use `sudo` or check file permissions | @@ -541,7 +541,7 @@ If you've tried the solutions above and still have problems: 1. **Collect debug information**: ```bash pipeops --version - pipeops auth status + pipeops status cat ~/.pipeops.json env | grep PIPEOPS ``` @@ -549,7 +549,7 @@ If you've tried the solutions above and still have problems: 2. **Create a minimal reproduction**: ```bash # Document exact steps to reproduce - pipeops auth login + pipeops login pipeops project list # etc. ``` From d242561bbb0c197250a0ee6922d54c8367bb0d76 Mon Sep 17 00:00:00 2001 From: Alex Idowu Date: Thu, 16 Jul 2026 12:02:30 +0100 Subject: [PATCH 7/7] Update CLI auth command docs --- docs/cli/advanced/cicd.md | 4 +- docs/cli/advanced/docker.md | 6 +- docs/cli/commands/authentication.md | 70 +++++++++++------------ docs/cli/commands/overview.md | 29 +++++----- docs/cli/getting-started/configuration.md | 12 ++-- docs/cli/getting-started/installation.md | 2 +- docs/cli/getting-started/quick-start.md | 8 +-- docs/cli/overview.md | 2 +- docs/cli/reference/troubleshooting.md | 20 +++---- 9 files changed, 76 insertions(+), 77 deletions(-) diff --git a/docs/cli/advanced/cicd.md b/docs/cli/advanced/cicd.md index 009f41c..f3a398f 100644 --- a/docs/cli/advanced/cicd.md +++ b/docs/cli/advanced/cicd.md @@ -356,7 +356,7 @@ Always handle errors gracefully: set -e # Check authentication -if ! pipeops auth status > /dev/null 2>&1; then +if ! pipeops status > /dev/null 2>&1; then echo "Authentication failed" exit 1 fi @@ -469,7 +469,7 @@ pipeops --version echo $PIPEOPS_AUTH_TOKEN | wc -c # Test authentication -pipeops auth status +pipeops status ``` #### JSON Parsing Errors diff --git a/docs/cli/advanced/docker.md b/docs/cli/advanced/docker.md index f79b070..8c0cc0d 100644 --- a/docs/cli/advanced/docker.md +++ b/docs/cli/advanced/docker.md @@ -35,7 +35,7 @@ To maintain authentication between container runs, mount the configuration direc ```bash docker run -it --rm \ -v ~/.pipeops:/root/.pipeops \ - pipeops/cli:latest auth login + pipeops/cli:latest login ``` ### Using Environment Variables @@ -59,7 +59,7 @@ alias pipeops='docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:late Usage: ```bash -pipeops auth login +pipeops login pipeops list pipeops status proj-123 ``` @@ -97,7 +97,7 @@ jobs: monitor: image: pipeops/cli:latest script: - - pipeops auth status + - pipeops status - pipeops list - pipeops status proj-123 variables: diff --git a/docs/cli/commands/authentication.md b/docs/cli/commands/authentication.md index 1534746..044423f 100644 --- a/docs/cli/commands/authentication.md +++ b/docs/cli/commands/authentication.md @@ -6,16 +6,16 @@ description: "Reference for PipeOps CLI authentication commands covering login w # Authentication Commands -The `pipeops auth` commands manage authentication and user account information. These commands handle login, logout, and session management for the PipeOps CLI. +The PipeOps CLI authentication commands manage login, logout, session status, and user account information. -## `pipeops auth login` +## `pipeops login` Authenticate with PipeOps using OAuth 2.0 with PKCE flow. ### Usage ```bash -pipeops auth login [flags] +pipeops login [flags] ``` ### Description @@ -33,12 +33,12 @@ Opens your default web browser to complete OAuth authentication. Once authentica **Standard login**: ```bash -pipeops auth login +pipeops login ``` **Login without opening browser**: ```bash -pipeops auth login --no-browser +pipeops login --no-browser ``` Output: @@ -73,13 +73,13 @@ The CLI uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authen **Browser doesn't open**: ```bash # Manually copy and open the URL -pipeops auth login --no-browser +pipeops login --no-browser ``` **Authentication timeout**: ```bash # Restart the process -pipeops auth login +pipeops login ``` **Permission denied**: @@ -90,19 +90,19 @@ chmod 600 ~/.pipeops.json --- -## `pipeops auth logout` +## `pipeops logout` Sign out and remove local credentials. ### Usage ```bash -pipeops auth logout [flags] +pipeops logout [flags] ``` ### Description -Removes the authentication token from local configuration. After logout, you'll need to run `pipeops auth login` again to use authenticated commands. +Removes the authentication token from local configuration. After logout, you'll need to run `pipeops login` again to use authenticated commands. ### Flags @@ -114,7 +114,7 @@ Removes the authentication token from local configuration. After logout, you'll **Standard logout**: ```bash -pipeops auth logout +pipeops logout ``` Output: @@ -125,7 +125,7 @@ Are you sure you want to logout? [y/N] y **Force logout without confirmation**: ```bash -pipeops auth logout --force +pipeops logout --force ``` ### What Gets Removed @@ -140,14 +140,14 @@ Logging out does **not** revoke the token on the server. To fully revoke access, --- -## `pipeops auth status` +## `pipeops status` Check current authentication status. ### Usage ```bash -pipeops auth status [flags] +pipeops status [flags] ``` ### Description @@ -158,7 +158,7 @@ Verifies if you're currently authenticated and displays session information. **Check auth status**: ```bash -pipeops auth status +pipeops status ``` Output when authenticated: @@ -170,12 +170,12 @@ Token expires: 2024-12-31 23:59:59 Output when not authenticated: ``` ✗ Not authenticated -Run 'pipeops auth login' to authenticate +Run 'pipeops login' to authenticate ``` **JSON output**: ```bash -pipeops auth status --json +pipeops status --json ``` ```json @@ -198,25 +198,25 @@ pipeops auth status --json ```bash # Check if authenticated before running commands -if pipeops auth status > /dev/null 2>&1; then +if pipeops status > /dev/null 2>&1; then echo "Authenticated, proceeding..." pipeops project list else echo "Not authenticated, please login" - pipeops auth login + pipeops login fi ``` --- -## `pipeops auth me` +## `pipeops me` Display current user information. ### Usage ```bash -pipeops auth me [flags] +pipeops me [flags] ``` ### Description @@ -227,7 +227,7 @@ Shows detailed information about the currently authenticated user. **View user info**: ```bash -pipeops auth me +pipeops me ``` Output: @@ -241,7 +241,7 @@ Account ID: usr_1234567890 **JSON output**: ```bash -pipeops auth me --json +pipeops me --json ``` ```json @@ -275,7 +275,7 @@ For CI/CD pipelines, use environment variables instead of interactive login: export PIPEOPS_AUTH_TOKEN=${{ secrets.PIPEOPS_TOKEN }} # Verify authentication -pipeops auth status +pipeops status # Run commands pipeops list @@ -288,10 +288,10 @@ Manage multiple PipeOps accounts using different config files: ```bash # Login to production account -PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops auth login +PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops login # Login to staging account -PIPEOPS_CONFIG_PATH=~/.pipeops-staging.json pipeops auth login +PIPEOPS_CONFIG_PATH=~/.pipeops-staging.json pipeops login # Use specific account alias pipeops-prod='PIPEOPS_CONFIG_PATH=~/.pipeops-prod.json pipeops' @@ -319,8 +319,8 @@ Best practices for token management: 4. **Rotate tokens regularly**: ```bash - pipeops auth logout - pipeops auth login + pipeops logout + pipeops login ``` ### Headless Servers @@ -329,7 +329,7 @@ For servers without a browser: ```bash # On the headless server -pipeops auth login --no-browser +pipeops login --no-browser # Copy the URL and open it on your local machine # After authorization, the server CLI will authenticate automatically @@ -354,23 +354,23 @@ echo '{"auth_token":"your-token-here"}' > ~/.pipeops.json **"Not authenticated"**: ``` Error: not authenticated -Run 'pipeops auth login' to authenticate +Run 'pipeops login' to authenticate ``` -**Solution**: Run `pipeops auth login` +**Solution**: Run `pipeops login` **"Token expired"**: ``` Error: authentication token has expired -Run 'pipeops auth login' to re-authenticate +Run 'pipeops login' to re-authenticate ``` -**Solution**: Run `pipeops auth login` to refresh +**Solution**: Run `pipeops login` to refresh **"Invalid token"**: ``` Error: invalid authentication token -Run 'pipeops auth login' to re-authenticate +Run 'pipeops login' to re-authenticate ``` -**Solution**: Run `pipeops auth logout` then `pipeops auth login` +**Solution**: Run `pipeops logout` then `pipeops login` **"Permission denied"**: ``` diff --git a/docs/cli/commands/overview.md b/docs/cli/commands/overview.md index c314987..9f26479 100644 --- a/docs/cli/commands/overview.md +++ b/docs/cli/commands/overview.md @@ -17,7 +17,7 @@ pipeops [options] [flags] ### Examples ```bash -pipeops auth login +pipeops login pipeops list pipeops logs proj-123 --follow ``` @@ -29,7 +29,10 @@ pipeops logs proj-123 --follow Manage authentication and user accounts. ```bash -pipeops auth +pipeops login +pipeops logout +pipeops status +pipeops me ``` | Command | Description | @@ -150,7 +153,7 @@ Most commands support both interactive and non-interactive modes: **Interactive** (prompts for input): ```bash -pipeops auth login +pipeops login ``` **Non-Interactive** (all options via flags): @@ -231,7 +234,8 @@ Get help for any command: pipeops --help # Category help -pipeops auth --help +pipeops login --help +pipeops logout --help pipeops project --help # Specific command help @@ -242,28 +246,23 @@ pipeops logs --help ### Example Output ```bash -$ pipeops auth --help +$ pipeops login --help Authenticate with PipeOps Usage: - pipeops auth [flags] - -Available Commands: - login Authenticate with PipeOps using OAuth - logout Sign out and remove local credentials - status Check current authentication status - me Display current user information + pipeops login [flags] Flags: - -h, --help help for auth + --auth-url string OAuth2 authorization URL + -h, --help help for login Global Flags: --json Output in JSON format -v, --verbose Enable verbose output -q, --quiet Suppress non-essential output -Use "pipeops auth --help" for more information about a command. +Use "pipeops [command] --help" for more information about a command. ``` ## Command Aliases @@ -328,7 +327,7 @@ See [Configuration](/docs/cli/getting-started/configuration) for more details. set -e # Exit on error # Authenticate -pipeops auth status || pipeops auth login +pipeops status || pipeops login # List projects pipeops list diff --git a/docs/cli/getting-started/configuration.md b/docs/cli/getting-started/configuration.md index a572d17..2ecc449 100644 --- a/docs/cli/getting-started/configuration.md +++ b/docs/cli/getting-started/configuration.md @@ -33,7 +33,7 @@ The CLI stores its configuration in a JSON file located at: | Option | Description | Default | |--------|-------------|---------| | `api_url` | PipeOps API endpoint | `https://api.pipeops.io` | -| `auth_token` | Authentication token (set by `auth login`) | - | +| `auth_token` | Authentication token (set by `login`) | - | | `default_project` | Default project for commands | - | | `output_format` | Output format (`text`, `json`) | `text` | | `log_level` | Logging level (`debug`, `info`, `warn`, `error`) | `info` | @@ -63,7 +63,7 @@ Specify a custom location for the configuration file: ```bash export PIPEOPS_CONFIG_PATH=/path/to/custom/config.json -pipeops auth login +pipeops login ``` #### `PIPEOPS_API_URL` @@ -276,7 +276,7 @@ pipeops-staging status proj-123 ### Login Flow -When you run `pipeops auth login`, the CLI: +When you run `pipeops login`, the CLI: 1. Opens your browser for OAuth authentication 2. Receives an authorization code @@ -314,7 +314,7 @@ For CI/CD pipelines, use secrets management to store tokens securely. Tokens are automatically refreshed by the CLI. If authentication expires: ```bash -pipeops auth login +pipeops login ``` ## Project-Specific Configuration @@ -506,7 +506,7 @@ If the configuration file is corrupted: mv ~/.pipeops.json ~/.pipeops.json.backup # Create new configuration -pipeops auth login +pipeops login ``` ### Environment Variable Not Working @@ -529,7 +529,7 @@ To start fresh: ```bash rm ~/.pipeops.json -pipeops auth login +pipeops login ``` ## Next Steps diff --git a/docs/cli/getting-started/installation.md b/docs/cli/getting-started/installation.md index 98c1050..08159dc 100644 --- a/docs/cli/getting-started/installation.md +++ b/docs/cli/getting-started/installation.md @@ -141,7 +141,7 @@ docker pull pipeops/cli:latest docker run -it --rm pipeops/cli:latest --help # Run with persistent configuration -docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:latest auth login +docker run -it --rm -v ~/.pipeops:/root/.pipeops pipeops/cli:latest login ``` For convenience, create an alias: diff --git a/docs/cli/getting-started/quick-start.md b/docs/cli/getting-started/quick-start.md index 0c6bc6d..9f407fe 100644 --- a/docs/cli/getting-started/quick-start.md +++ b/docs/cli/getting-started/quick-start.md @@ -19,7 +19,7 @@ This guide will help you get up and running with the PipeOps CLI in minutes. You First, authenticate with your PipeOps account: ```bash -pipeops auth login +pipeops login ``` This will: @@ -39,13 +39,13 @@ Opening browser for authentication... Check your authentication status: ```bash -pipeops auth status +pipeops status ``` View your account information: ```bash -pipeops auth me +pipeops me ``` ## Step 2: Create Your First Project @@ -286,7 +286,7 @@ Here's a complete workflow from authentication to monitoring: ```bash # 1. Authenticate -pipeops auth login +pipeops login # 2. List your projects pipeops list diff --git a/docs/cli/overview.md b/docs/cli/overview.md index bde4298..5205e04 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -58,7 +58,7 @@ The PipeOps Command Line Interface (CLI) is a powerful tool that enables you to The PipeOps CLI organizes commands into logical categories: -- **Authentication** (`pipeops auth`) - Login, logout, and account management +- **Authentication** (`pipeops login`, `pipeops logout`, `pipeops status`, `pipeops me`) - Login, logout, and account management - **Projects** (`pipeops project`) - Project lifecycle management - **Monitoring** (`pipeops list`, `pipeops status`, `pipeops logs`) - View project and addon information - **Servers** (`pipeops server`) - Server provisioning and management diff --git a/docs/cli/reference/troubleshooting.md b/docs/cli/reference/troubleshooting.md index 2695517..c7f7113 100644 --- a/docs/cli/reference/troubleshooting.md +++ b/docs/cli/reference/troubleshooting.md @@ -73,7 +73,7 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash ### Authentication Failed -**Problem**: `pipeops auth login` fails. +**Problem**: `pipeops login` fails. **Solutions**: @@ -85,12 +85,12 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash 2. **Clear existing configuration**: ```bash rm ~/.pipeops.json - pipeops auth login + pipeops login ``` 3. **Use manual browser authentication**: ```bash - pipeops auth login --no-browser + pipeops login --no-browser # Copy and paste the URL into your browser ``` @@ -102,8 +102,8 @@ sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash ```bash # Re-authenticate -pipeops auth logout -pipeops auth login +pipeops logout +pipeops login ``` ### Invalid Token @@ -125,7 +125,7 @@ pipeops auth login 3. **Re-authenticate**: ```bash - pipeops auth login + pipeops login ``` --- @@ -262,7 +262,7 @@ pipeops auth login ```bash mv ~/.pipeops.json ~/.pipeops.json.backup echo '{}' > ~/.pipeops.json - pipeops auth login + pipeops login ``` ### Environment Variables Not Working @@ -525,7 +525,7 @@ For persistent issues: | Error | Cause | Solution | |-------|-------|----------| | `command not found: pipeops` | CLI not in PATH | Add to PATH or reinstall | -| `not authenticated` | No valid auth token | Run `pipeops auth login` | +| `not authenticated` | No valid auth token | Run `pipeops login` | | `token expired` | Auth token expired | Re-authenticate | | `project not found` | Invalid project name | Check project name with `project list` | | `permission denied` | Insufficient permissions | Use `sudo` or check file permissions | @@ -541,7 +541,7 @@ If you've tried the solutions above and still have problems: 1. **Collect debug information**: ```bash pipeops --version - pipeops auth status + pipeops status cat ~/.pipeops.json env | grep PIPEOPS ``` @@ -549,7 +549,7 @@ If you've tried the solutions above and still have problems: 2. **Create a minimal reproduction**: ```bash # Document exact steps to reproduce - pipeops auth login + pipeops login pipeops project list # etc. ```