Merge pull request #70 from appcircleio/release/2.7.3

Release/2.7.3

Author: fuatguzel

README.md

@@ -65,6 +65,7 @@ Run `appcircle [commandName] --help` to view a list of  commands/subcommands in
 
 - [appcircle config](/docs/config/index.md)
 - [appcircle login](/docs/login/index.md)
+- [appcircle logout](/docs/logout/index.md)
 - [appcircle build](/docs/build/index.md)
 - [appcircle signing-identity](/docs/signing-identity/index.md)
 - [appcircle testing-distribution](/docs/testing-distribution/index.md)
@@ -105,6 +106,12 @@ Appcircle CLI incorporates a GUI that allows users to interactively access its f
 appcircle -i
 ```
 
+### Features
+- **Authentication Grouping**: Login and Logout options are grouped under "Authentication (Login/Logout)" menu
+- **Smart Navigation**: Use "⬅ Back" buttons to navigate between menus
+- **Login Protection**: Prevents multiple login attempts when already authenticated
+- **Intuitive UI**: Clean menu structure with proper navigation flow
+
 ### Demo
 ![Demo](https://cdn.appcircle.io/docs/assets/appcircle_gui_demo.gif)
 
@@ -144,10 +151,27 @@ CURL_LOGGING= appcircle
 
 ### Connecting Your Appcircle Account via CLI
 
+You can authenticate with Appcircle using either Personal Access Token or API Key:
+
+#### Using Personal Access Token
 - [Generate a personal access token from the Appcircle dashboard](https://docs.appcircle.io/appcircle-api/api-authentication#generatingmanaging-the-personal-api-tokens)
-- Using the Appcircle CLI, create a full access API token using the following command with the personal access token specified as "pat": `appcircle login --pat="YOUR PERSONAL ACCESS TOKEN"`.
+- Using the Appcircle CLI, create a full access API token using the following command: `appcircle login pat --token="YOUR PERSONAL ACCESS TOKEN"`.
+
+#### Using API Key
+- [Create an API Key from the Appcircle dashboard](https://docs.appcircle.io/appcircle-api/api-authentication#api-keys)
+- Using the Appcircle CLI, authenticate with your API Key: `appcircle login api-key --name="YOUR_API_KEY_NAME" --secret="YOUR_API_KEY_SECRET"`.
+- For multi-organization accounts, you can specify an organization: `appcircle login api-key --name="YOUR_API_KEY_NAME" --secret="YOUR_API_KEY_SECRET" --organization-id="YOUR_ORG_ID"`.
+
+#### Logout
+- To logout from your Appcircle account, use: `appcircle logout`
+- This will clear your stored authentication token locally
+
+#### Authentication Behavior
+- If you're already logged in and try to login again, you'll see a "You are already logged in" message
+- You must logout first before logging in with different credentials
+- Your token is stored locally and will persist until you logout or manually clear it
 
-> Your token will be stored internally. You should always revoke your access token if you do not plan to use it in the future.
+> Your token will be stored internally. You should always logout or revoke your access token if you do not plan to use it in the future.
 
 ### Starting a New Build via the Appcircle CLI
 
@@ -167,7 +191,7 @@ Appcircle CLI includes the following improvements for build log downloading func
 - User-friendly animation is displayed: "Waiting for build logs to be prepared..."
 - Support for manual log download with both task ID (`--taskId`) and commit/build ID (`--commitId`/`--buildId`) parameters
 - Automatic fallback to alternative download methods when the primary method fails
-- Log files are saved with descriptive filenames: `build-task-{taskId}-log.txt`
+- Log files are saved with descriptive filenames that include branch name, profile name, and timestamp: `{branchName}-{profileName}-build-logs-{timestamp}.txt`
 
 To download build logs:
 ```shell

docs/build/download-log.md

@@ -8,38 +8,44 @@ appcircle build download-log [options]
 
 ## Description
 
+Download Build Logs
+
 This command downloads build logs using either a Task ID (preferred) or a Commit ID and Build ID combination. When using the Task ID method, the CLI automatically waits for logs to be ready, checking at 5-second intervals for up to 2 minutes.
 
-The downloaded log file will be saved as `build-task-{taskId}-log.txt` or `{buildId}-log.txt` depending on the method used.
+The downloaded log file will be saved with a descriptive name that includes the branch name, profile name, and timestamp: `{branchName}-{profileName}-build-logs-{timestamp}.txt`. If branch name or profile name is not available, they will be replaced with 'unknown'. All special characters in names are replaced with underscores for filesystem safety.
 
 ## Features
 
 - User-friendly animation is displayed while build logs are being prepared
 - Automatically switches to alternative download methods if the primary method fails
-- Logs are saved with descriptive filenames: `build-task-{taskId}-log.txt` or `{buildId}-log.txt`
+- Logs are saved with descriptive, sanitized filenames that include branch name, profile name, and timestamp
 - Full file path is displayed to easily find log files
 
 ## Options
 
 ```plaintext
-  --path <string>     [OPTIONAL] Path where logs will be downloaded. Defaults to current directory or Downloads folder
-
-  --taskId <uuid>     [METHOD 1] Task ID for the build process
-
-  --commitId <uuid>   [METHOD 2] Commit ID
-
-  --buildId <uuid>    [METHOD 2] Build ID
+  --path <string>      [OPTIONAL] Path where logs will be downloaded. Defaults to current directory or Downloads folder
+  --taskId <uuid>      [METHOD 1] Task ID for the build process
+  --profileId <uuid>   Build profile ID
+  --profile <string>   Build profile name (alternative to --profileId)
+  --branchId <uuid>    Branch ID
+  --branch <string>    Branch name (alternative to --branchId)
+  --commitId <uuid>    [METHOD 2] Commit ID
+  --buildId <uuid>     [METHOD 2] Build ID
 ```
 
 ## Examples
 
-```plaintext
+```bash
 # Download logs using Task ID (preferred method)
 appcircle build download-log --taskId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
 
-# Download logs using Commit ID and Build ID
-appcircle build download-log --commitId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" --buildId="7q8r9s0t-1u2v-3w4x-5y6z-7a8b9c0d1e2f"
+# Download logs using profile and branch names
+appcircle build download-log --profile "Automation Variable" --branch "develop" --commitId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" --buildId="7q8r9s0t-1u2v-3w4x-5y6z-7a8b9c0d1e2f"
+
+# Download logs using IDs
+appcircle build download-log --profileId 8ad65c77-9ed8-4664-a6e1-4bf7032d33cd --branchId f416f868-5d1a-4464-8ff7-70ddb789aeba --commitId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" --buildId="7q8r9s0t-1u2v-3w4x-5y6z-7a8b9c0d1e2f"
 
 # Download to a specific directory
-appcircle build download-log --taskId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" --path="/Users/username/Downloads"
-``` 
+appcircle build download-log --profile "Automation Variable" --branch "develop" --commitId="1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" --buildId="7q8r9s0t-1u2v-3w4x-5y6z-7a8b9c0d1e2f" --path="/Users/username/Downloads"
+```

docs/build/download.md

@@ -1,22 +1,48 @@
 # `appcircle build download`
 
+## Description
+Download Artifacts
+
 Download your artifact to the given directory on your machine.
 
 ```plaintext
 appcircle build download [options]
 ```
 
-## Options
+## Artifact Filename
 
-```plaintext
-  --path <string>    [OPTIONAL] The path for artifacts to be downloaded. Defaults to the current directory
+By default, the downloaded artifact will be saved as `artifacts-{timestamp}.zip`, where `{timestamp}` is the current date and time in `YYYYMMDD-HHMMSS` format. This ensures each download has a unique filename.
 
-  --commitId <uuid>  Commit ID of your build
+## Download Path
+
+If the `--path` option is not specified, the artifact will be downloaded to your system's `~/Downloads` directory by default.
+
+## Options
 
-  --buildId <uuid>   Build ID
+```plaintext
+  --path <string>      [OPTIONAL] The path for artifacts to be downloaded. Defaults to ~/Downloads if not specified.
+  --profileId <uuid>   Build profile ID
+  --profile <string>   Build profile name (alternative to --profileId)
+  --branchId <uuid>    Branch ID
+  --branch <string>    Branch name (alternative to --branchId)
+  --commitId <uuid>    Commit ID of your build
+  --buildId <uuid>     Build ID
 ```
 ## Options inherited from parent commands
 
 ```plaintext
       --help   Show help for command
 ```
+
+## Examples
+
+```bash
+# Using IDs
+appcircle build download --profileId 8ad65c77-9ed8-4664-a6e1-4bf7032d33cd --branchId f416f868-5d1a-4464-8ff7-70ddb789aeba --commitId b96329d3-fd56-4030-8073-c13c61d288c4 --buildId 6528b1b9-359c-4589-b29d-c249a2f690ee
+
+# Using names instead of IDs
+appcircle build download --profile "Automation Variable" --branch "develop" --commitId b96329d3-fd56-4030-8073-c13c61d288c4 --buildId 6528b1b9-359c-4589-b29d-c249a2f690ee
+
+# Mixed usage with custom path
+appcircle build download --profile "Automation Variable" --branchId f416f868-5d1a-4464-8ff7-70ddb789aeba --commitId b96329d3-fd56-4030-8073-c13c61d288c4 --buildId 6528b1b9-359c-4589-b29d-c249a2f690ee --path ./artifacts
+```

docs/build/list.md

@@ -9,10 +9,27 @@ appcircle build list [options]
 ## Options
 
 ```plaintext
-  --commitId <uuid>  Commit ID
+  --profileId <uuid>   Build profile ID
+  --profile <string>   Build profile name (alternative to --profileId)
+  --branchId <uuid>    Branch ID
+  --branch <string>    Branch name (alternative to --branchId)
+  --commitId <uuid>    Commit ID
 ```
 ## Options inherited from parent commands
 
 ```plaintext
       --help   Show help for command
 ```
+
+## Examples
+
+```bash
+# Using IDs
+appcircle build list --profileId 8ad65c77-9ed8-4664-a6e1-4bf7032d33cd --branchId f416f868-5d1a-4464-8ff7-70ddb789aeba --commitId b96329d3-fd56-4030-8073-c13c61d288c4
+
+# Using names instead of IDs
+appcircle build list --profile "Automation Variable" --branch "develop" --commitId b96329d3-fd56-4030-8073-c13c61d288c4
+
+# Mixed usage (IDs and names)
+appcircle build list --profile "Automation Variable" --branchId f416f868-5d1a-4464-8ff7-70ddb789aeba --commitId b96329d3-fd56-4030-8073-c13c61d288c4
+```

docs/build/start.md

@@ -8,18 +8,157 @@ appcircle build start [options]
 
 ## Options
 
+### Required Parameters
 ```plaintext
   --profileId <uuid>        Build profile ID
-  --branchId <uuid>         Branch ID
-  --commitId <uuid>         Commit ID [Optional]
-  --configurationId <uuid>  Configuration ID [Optional]
+  --profile <string>        Build profile name (alternative to --profileId)
   --workflowId <uuid>       Workflow ID
-  --branch <string>         Branch Name instead of 'branch ID'
-  --workflow <string>       Workflow Name instead of 'workflow ID'
-  --commitHash <string>     Commit Hash instead of 'Commit ID' [Optional]
+  --workflow <string>       Workflow name (alternative to --workflowId)
 ```
+
+### Conditional Parameters
+```plaintext
+  --branchId <uuid>        Appcircle branch ID,. Required when --commitId is not provided
+  --branch <string>         Git branch name (alternative to --branchId). Required when --commitId is not provided
+  --commitId <uuid>         Appcircle commit ID . Required when --branchId is not provided
+  --commitHash <string>     Git commit hash (alternative to --commitId). Required when --branchId is not provided
+```
+
+### Optional Parameters
+```plaintext
+  --configurationId <uuid>  Configuration ID
+  --configuration <string>  Configuration name (alternative to --configurationId)
+  --no-wait                 Don't wait for build completion, return immediately with task info
+  --download-logs           Automatically download build logs after completion
+  --download-artifacts      Automatically download build artifacts after completion
+  --path <string>           Download path for logs and artifacts (default: ~/Downloads)
+```
+
 ## Options inherited from parent commands
 
 ```plaintext
       --help   Show help for command
 ```
+
+## Parameter Logic
+
+### Profile Selection
+- **Required**: Either `--profileId` or `--profile` must be provided
+- **Example**: `--profileId 550e8400-e29b-41d4-a716-446655440000` or `--profile "My iOS Project"`
+
+### Workflow Selection
+- **Required**: Either `--workflowId` or `--workflow` must be provided
+- **Example**: `--workflowId 6ba7b811-9dad-11d1-80b4-00c04fd430c8` or `--workflow "Default Push Workflow"`
+
+### Commit vs Branch Selection
+You must provide either commit information OR branch information:
+
+#### Option 1: Specify Commit (Branch becomes optional)
+```bash
+# Using commit ID
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid>
+
+# Using commit hash
+appcircle build start --profileId <uuid> --commitHash <hash> --workflowId <uuid>
+```
+
+#### Option 2: Specify Branch (uses latest commit from branch)
+```bash
+# Using branch ID
+appcircle build start --profileId <uuid> --branchId <uuid> --workflowId <uuid>
+
+# Using branch name
+appcircle build start --profileId <uuid> --branch "main" --workflowId <uuid>
+```
+
+### Configuration Selection
+- **Optional**: If not provided, uses the first available configuration for the profile
+- **Example**: `--configurationId <uuid>` or `--configuration "Debug Configuration"`
+
+## Usage Examples
+
+### Basic Usage
+
+#### 1. Build with Specific Commit
+```bash
+appcircle build start --profileId 550e8400-e29b-41d4-a716-446655440000 --commitId 6ba7b812-9dad-11d1-80b4-00c04fd430c8 --workflowId 6ba7b811-9dad-11d1-80b4-00c04fd430c8
+```
+
+#### 2. Build with Branch (uses latest commit)
+```bash
+appcircle build start --profileId 550e8400-e29b-41d4-a716-446655440000 --branchId 6ba7b810-9dad-11d1-80b4-00c04fd430c8 --workflowId 6ba7b811-9dad-11d1-80b4-00c04fd430c8
+```
+
+#### 3. Build with Names Instead of IDs
+```bash
+appcircle build start --profile "My iOS Project" --branch "main" --workflow "Default Push Workflow"
+```
+
+### Advanced Usage
+
+#### 4. Build with Configuration
+```bash
+appcircle build start --profileId <uuid> --commitId <uuid> --configurationId <uuid> --workflowId <uuid>
+```
+
+#### 5. Automation (No Wait)
+```bash
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid> --no-wait
+```
+
+#### 6. Build with Auto-Download
+```bash
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid> --download-logs --download-artifacts
+```
+
+#### 7. Build with Custom Download Path
+```bash
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid> --download-artifacts --path "/custom/path"
+```
+
+#### 8. Mixed Usage (IDs and Names)
+```bash
+appcircle build start --profile "My Android App" --branchId 6ba7b810-9dad-11d1-80b4-00c04fd430c8 --workflow "Default Push Workflow"
+```
+
+## Common Scenarios
+
+### Scenario 1: Build Latest Commit from Branch
+```bash
+# When you want to build the latest commit from a specific branch
+appcircle build start --profileId <uuid> --branchId <uuid> --workflowId <uuid>
+```
+
+### Scenario 2: Build Specific Commit
+```bash
+# When you want to build a specific commit (branch info not needed)
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid>
+```
+
+### Scenario 3: Automation Pipeline
+```bash
+# For CI/CD pipelines where you don't want to wait for completion
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid> --no-wait
+```
+
+### Scenario 4: Build with Artifacts
+```bash
+# When you need logs and artifacts after build completion
+appcircle build start --profileId <uuid> --commitId <uuid> --workflowId <uuid> --download-logs --download-artifacts
+```
+
+## Notes
+
+- **Commit vs Branch**: When you provide `--commitId`, the system doesn't need branch information since the commit is already specified. When you provide `--branchId`, the system automatically uses the latest commit from that branch.
+
+- **Configuration**: If `--configurationId` is not provided, the system uses the first available configuration for the profile.
+
+- **No Wait**: The `--no-wait` parameter is useful for automation scenarios where you don't want to wait for build completion. The command returns immediately with task information.
+
+- **Auto Download**: The `--download-logs` and `--download-artifacts` parameters automatically download files after build completion. Use `--path` to specify a custom download location.
+
+## Learn More
+
+- Use `appcircle build profile list` to get available profiles with their UUIDs and names
+- Use `appcircle build profile branch list --profileId <uuid>` to get available branches
+- Use `appcircle build profile workflows --profileId <uuid>` to get available workflows

docs/build/variable/group/download.md

@@ -0,0 +1,28 @@
+# `appcircle build variable group download`
+
+Download Build environment variables as a JSON file
+
+```plaintext
+appcircle build variable group download [options]
+```
+
+## Examples
+
+```plaintext
+$ appcircle build variable group download --variableGroupId "Variable Group ID"
+
+$ appcircle build variable group download --variableGroupId "Variable Group ID" --path "/path/to/save"
+```
+         
+## Options
+
+```plaintext
+      --variableGroupId <uuid>  Variable Group ID
+      --path <string>           [OPTIONAL] The path for JSON file to be downloaded (Defaults to the current directory)
+```                       
+
+## Options inherited from parent commands
+
+```plaintext
+      --help   Show help for command
+```