diff --git a/README.md b/README.md index 8739496b..4f7533f0 100644 --- a/README.md +++ b/README.md @@ -1,467 +1,179 @@ -# ipctl +# 💻 ipctl -A powerful command-line interface for managing Itential Platform servers. `ipctl` provides intuitive commands for working with 35+ resource types including projects, workflows, automations, adapters, accounts, groups, and more. +A CLI for managing Itential Platform servers — get, create, import, export, and copy 35+ resource types from the command line. -## Features - -- **Resource Management**: Full CRUD operations (create, read, update, delete) for all Itential Platform resources -- **Import/Export**: Git-based asset import/export with SSH authentication support -- **Multi-Instance Support**: Profile-based configuration for managing multiple Itential Platform servers -- **Flexible Authentication**: OAuth2 client credentials flow or basic authentication -- **Multiple Output Formats**: Human-readable, JSON, YAML, or custom templates -- **Asset Orchestration**: Copy automations, workflows, and other assets between environments -- **Local Development**: Built-in MongoDB-backed AAA server for local testing - -## Installation - -### Homebrew (macOS and Linux) - -The easiest way to install `ipctl` on macOS or Linux is via Homebrew: +![ipctl version](assets/gifs/ipctl-version.gif) -```bash -# Add the Itential tap -brew tap itential/tap - -# Install ipctl -brew install ipctl - -# Verify installation -ipctl --version -``` - -To upgrade to the latest version: - -```bash -brew upgrade ipctl -``` +## Quick Start -### Manual Installation +### Install Download the latest release for your platform from the [releases page](https://github.com/itential/ipctl/releases): ```bash -# Example for Linux x64 +# Linux x64 curl -LO https://github.com/itential/ipctl/releases/latest/download/ipctl-linux-x86_64.tar.gz tar -xzf ipctl-linux-x86_64.tar.gz sudo mv ipctl /usr/local/bin/ -chmod +x /usr/local/bin/ipctl +``` -# Verify installation -ipctl --version +
+Build from source + +```bash +git clone https://github.com/itential/ipctl.git && cd ipctl +make build +./bin/ipctl --version ``` -## Quick Start +
-### 1. Configure a Profile +### Configure -Create a configuration file at `~/.platform.d/config.toml`: +Create `~/.platform.d/config.toml` with a server profile: ```toml -["profile production"] +["profile default"] host = "platform.example.com" port = 443 -scheme = "https" +use_tls = true username = "admin" password = "your-password" - -["profile staging"] -host = "staging.example.com" -port = 443 -scheme = "https" -client_id = "your-client-id" -client_secret = "your-client-secret" ``` -### 2. List Resources +### Use -```bash -# List all projects on production -ipctl get projects --profile production +![ipctl workflow](assets/gifs/ipctl-workflow.gif) -# List workflows with JSON output -ipctl get workflows --profile staging --output json +## Features -# Get specific automation by name -ipctl get automation "Deploy Network Config" -``` +| Feature | Description | +|---------|-------------| +| **Resource CRUD** | Get, create, update, and delete 35+ resource types | +| **Import / Export** | Move assets via local directories or Git repositories with SSH auth | +| **Multi-Instance** | Named profiles for managing multiple Platform servers | +| **Authentication** | OAuth2 client credentials or basic auth with TLS | +| **Output Formats** | Human-readable tables, JSON, YAML, or custom Go templates | +| **Cross-Environment** | Copy automations, workflows, and assets between servers | -### 3. Export Assets +## Configuration -```bash -# Export a project to local directory -ipctl export project MyProject --destination ./exports/ +`ipctl` loads configuration from `~/.platform.d/config` by default. Supports INI, YAML, TOML, and JSON formats (auto-detected by file extension). -# Export to Git repository -ipctl export project MyProject \ - --repository git@github.com:org/repo.git \ - --branch main +### Profile Options -# Export automation with dependencies -ipctl export automation "My Automation" \ - --include-dependencies \ - --destination ./my-automation/ -``` +| Option | Description | Default | +|--------|-------------|---------| +| `host` | Platform server hostname | `localhost` | +| `port` | Server port (0 = auto from `use_tls`) | `0` | +| `use_tls` | Enable TLS connection | `true` | +| `verify` | Verify TLS certificates | `true` | +| `username` | Basic auth username | - | +| `password` | Basic auth password | - | +| `client_id` | OAuth2 client ID | - | +| `client_secret` | OAuth2 client secret | - | +| `timeout` | Request timeout in seconds (0 = disabled) | `0` | -### 4. Import Assets +Authentication requires either `username`/`password` or `client_id`/`client_secret`. -```bash -# Import from local directory -ipctl import project ./my-project/ --profile production - -# Import from Git repository -ipctl import project \ - --repository https://github.com/org/repo.git \ - --branch main \ - --profile staging -``` +### Environment Variables -### 5. Copy Between Environments +Override any profile value with `IPCTL_PROFILE__`: ```bash -# Copy automation from staging to production -ipctl copy automation "Deploy Config" \ - --from staging \ - --to production +export IPCTL_PROFILE_PROD_PASSWORD=secret +ipctl get projects --profile prod ``` -## Configuration - -### Configuration File - -The configuration file supports multiple formats (INI, YAML, TOML, JSON). By default, `ipctl` looks for `~/.platform.d/config`. Here's a TOML example: - -```toml -["profile default"] -host = "localhost" -port = 3000 -scheme = "http" -username = "admin@itential.com" -password = "admin" - -["profile production"] -host = "prod.example.com" -port = 443 -scheme = "https" -client_id = "your-client-id" -client_secret = "your-client-secret" -verify_ssl = true -``` +### Precedence -**Note:** You can use `.ini`, `.yaml`, `.yml`, `.toml`, or `.json` extensions. The format is automatically detected. See [Configuration Reference](docs/configuration-reference.md) for examples in all formats. +CLI flags > environment variables > config file > defaults -### Configuration Options +See the [Configuration Reference](docs/configuration-reference.md) for complete details including multi-format examples. -| Option | Description | Required | Default | -|--------|-------------|----------|---------| -| `host` | Platform server hostname | Yes | - | -| `port` | Server port | No | 443 | -| `scheme` | Protocol (http/https) | No | https | -| `username` | Basic auth username | No* | - | -| `password` | Basic auth password | No* | - | -| `client_id` | OAuth2 client ID | No* | - | -| `client_secret` | OAuth2 client secret | No* | - | -| `verify_ssl` | Verify SSL certificates | No | true | +## Supported Resources -*Either `username`/`password` or `client_id`/`client_secret` required for authentication. - -### Environment Variables - -Override configuration values using environment variables with the `IPCTL_` prefix: - -```bash -export IPCTL_HOST=platform.example.com -export IPCTL_CLIENT_ID=your-client-id -export IPCTL_CLIENT_SECRET=your-client-secret - -ipctl get projects -``` +| Category | Resources | +|----------|-----------| +| **Automation Studio** | projects, workflows, automations, templates, transformations, jsonforms | +| **Admin** | accounts, groups, roles, adapters, integrations, prebuilts, tags | +| **Configuration Manager** | devices, device-groups, configuration-parsers, gctrees | +| **Lifecycle Manager** | models | -### Configuration Precedence - -Configuration values are resolved in the following order (highest to lowest): - -1. Command-line flags -2. Environment variables (`IPCTL_*`) -3. Configuration file (`~/.platform.d/config`) -4. Default values +See the [Command Quick Reference](docs/commands-quick-reference.md) for the full matrix of supported operations per resource. ## Usage Examples -### Working with Projects +
+Working with projects ```bash -# List all projects ipctl get projects - -# Get project details ipctl describe project "My Project" - -# Create a new project ipctl create project "New Project" --description "Project description" - -# Delete a project ipctl delete project "Old Project" - -# Export project with Git ipctl export project "My Project" \ --repository git@github.com:org/repo.git \ - --branch main \ - --commit-message "Export project" + --branch main ``` -### Working with Automations +
+ +
+Working with automations ```bash -# List automations ipctl get automations - -# Get automation details with JSON output ipctl describe automation "Deploy Config" --output json - -# Import automation from Git ipctl import automation \ --repository https://github.com/org/automations.git \ --reference v1.0.0 - -# Copy automation between environments ipctl copy automation "Deploy Config" --from dev --to staging ``` -### Working with Workflows - -```bash -# List workflows -ipctl get workflows - -# Describe workflow with custom template -ipctl describe workflow "My Workflow" --template custom.tmpl - -# Export workflow to directory -ipctl export workflow "My Workflow" --destination ./workflows/ - -# Import workflow -ipctl import workflow ./workflows/my-workflow.json -``` +
-### Working with Adapters +
+Working with adapters ```bash -# List all adapters ipctl get adapters - -# Get adapter details ipctl describe adapter "ServiceNow" - -# Start adapter ipctl start adapter "ServiceNow" - -# Stop adapter ipctl stop adapter "ServiceNow" - -# Restart adapter ipctl restart adapter "ServiceNow" ``` -### Working with Accounts and Groups - -```bash -# List accounts -ipctl get accounts - -# Create account -ipctl create account "user@example.com" \ - --password "password" \ - --first-name "John" \ - --last-name "Doe" - -# List groups -ipctl get groups - -# Create group -ipctl create group "Operators" --description "Network operators" - -# Add user to group -ipctl update group "Operators" --add-member "user@example.com" -``` - -### Output Formats - -```bash -# Human-readable output (default) -ipctl get projects - -# JSON output -ipctl get projects --output json - -# YAML output -ipctl get projects --output yaml - -# Custom template -ipctl describe project "My Project" --template my-template.tmpl - -# No color output -ipctl get projects --no-color -``` - -## Resource Types - -`ipctl` supports management of the following resource types: - -### Assets -- Projects -- Workflows -- Automations -- Templates (JSON, Command, Jinja, Analytic) -- Transformations -- Forms -- Operations Manager (OM) instances - -### Platform Resources -- Accounts -- Groups -- Roles -- Adapters -- Integrations -- Application instances -- Tags - -### Configuration -- Profiles (user profiles, not connection profiles) -- Variables - -### Advanced -- Datasets (when feature flag enabled) -- Models -- Device groups - -## Development - -### Prerequisites - -- Go 1.24 or later -- Make -- Git - -### Building from Source - -```bash -# Clone repository -git clone https://github.com/itential/ipctl.git -cd ipctl - -# Install dependencies -make install - -# Build -make build - -# Binary will be in ./bin/ipctl -./bin/ipctl --version -``` - -### Running Tests - -```bash -# Run all tests -make test - -# Run tests with coverage -make coverage - -# Run specific test -go test ./pkg/services/... - -# Debug tests -scripts/test.sh debugtest -``` - -### Project Structure - -``` -ipctl/ -├── cmd/ipctl/ # Application entry point -├── internal/ # Private application code -│ ├── cli/ # CLI setup and command tree -│ ├── handlers/ # Command handlers -│ ├── runners/ # Operation execution -│ ├── flags/ # CLI flag definitions -│ ├── config/ # Configuration management -│ └── profile/ # Profile management -├── pkg/ # Public libraries -│ ├── client/ # HTTP client -│ ├── services/ # API operations -│ ├── resources/ # Business logic -│ └── validators/ # Input validation -├── docs/ # Documentation -└── scripts/ # Build and test scripts -``` +
-For detailed architecture documentation, see [CLAUDE.md](CLAUDE.md). +
+Output formats -### Contributing +![ipctl output formats](assets/gifs/ipctl-output-formats.gif) -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Make your changes -4. Run tests (`make test`) -5. Commit your changes (`git commit -m 'Add amazing feature'`) -6. Push to the branch (`git push origin feature/amazing-feature`) -7. Open a Pull Request +
## Documentation -- [Configuration Reference](docs/configuration-reference.md) - Complete configuration options -- [CLAUDE.md](CLAUDE.md) - Comprehensive architecture and development guide -- [Command Reference](docs/commands.md) - Detailed command documentation (if available) +- [Configuration Reference](docs/configuration-reference.md) — profile options, formats, environment variables +- [Command Quick Reference](docs/commands-quick-reference.md) — operations matrix per resource +- [API Command Reference](docs/api-command-reference.md) — detailed API command docs +- [Working with Repositories](docs/working-with-repositories.md) — Git-based import/export +- [Logging Reference](docs/logging-reference.md) — log levels, JSON output, sensitive data redaction +- [Running from Source](docs/running-from-source.md) — development setup -## Common Issues +## Contributing -### Authentication Failures +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branch conventions, and the pull request process. -```bash -# Verify profile configuration -cat ~/.platform.d/config - -# Test connection with verbose output -ipctl get projects --profile myprofile --verbose - -# Check environment variables -env | grep IPCTL -``` - -### SSL Certificate Errors - -```bash -# Disable SSL verification (not recommended for production) -ipctl get projects --profile myprofile --verify-ssl=false - -# Or set in profile config -["profile myprofile"] -verify_ssl = false -``` - -### Profile Not Found - -```bash -# List available profiles -grep "profile" ~/.platform.d/config - -# Use specific profile -ipctl get projects --profile production - -# Set default profile in your config file -["profile default"] -host = "your-default-host.com" -``` +All contributors must sign the [Contributor License Agreement](CLA.md) before contributions can be merged. ## License -Copyright 2024 Itential Inc. All Rights Reserved. +This project is licensed under the [GNU General Public License v3.0](LICENSE). -Unauthorized copying of this software, via any medium is strictly prohibited. Proprietary and confidential. ## Support -For issues and questions: -- GitHub Issues: https://github.com/itential/ipctl/issues -- Documentation: https://docs.itential.com +- [GitHub Issues](https://github.com/itential/ipctl/issues) +- [Itential Documentation](https://docs.itential.com) diff --git a/assets/gifs/.gif-create.yml b/assets/gifs/.gif-create.yml new file mode 100644 index 00000000..abd47a33 --- /dev/null +++ b/assets/gifs/.gif-create.yml @@ -0,0 +1,57 @@ +# .gif-create.yml +# Itential brand configuration for terminal GIF recordings +# Colors sourced from Itential Brand Guidelines (January 2022) + +brand: + # Custom colors derived from Itential brand palette + colors: + background: "#101625" # Navy (primary brand color) + foreground: "#FFFFFF" # White (body text on dark backgrounds) + cursor: "#FFFFFF" # White (matches foreground) + cursorAccent: "#101625" # Navy (text inside cursor block) + border: "#1B93D2" # Bright Blue (primary accent) + selection: "#1B93D2" # Bright Blue (selection highlight) + # ANSI colors mapped to Itential brand palette + black: "#101625" # Navy + red: "#FF6633" # Orange (secondary palette) + green: "#99CA3C" # Green (secondary palette) + yellow: "#FFAC73" # Light Orange (extended palette) + blue: "#1B93D2" # Bright Blue (primary palette) + magenta: "#C5258F" # Pink (secondary palette) + cyan: "#E5F2FE" # Light Blue (secondary palette) + white: "#FFFFFF" # White + brightBlack: "#414042" # 90% Grey (text color) + brightRed: "#FF6633" # Orange + brightGreen: "#99CA3C" # Green + brightYellow: "#FFAC73" # Light Orange + brightBlue: "#1B93D2" # Bright Blue + brightMagenta: "#C5258F" # Pink + brightCyan: "#E5F2FE" # Light Blue + brightWhite: "#FFFFFF" # White + + # Typography + font_family: "MonoLisa, Menlo, monospace" + font_size: 14 + line_height: 1.4 + letter_spacing: 0 + padding: 20 + + # Terminal chrome + border_radius: 8 + margin: 4 + margin_fill: "#0D1018" + window_bar: "Colorful" + + # Prompt styling + prompt: "bold" + prompt_color: "#C5258F" # Pink (secondary palette) + +# Default output settings +defaults: + preset: "github-readme" + typing_speed: "50ms" + +# Directory conventions +paths: + tapes: "assets/gifs/tapes" + output: "assets/gifs" diff --git a/assets/gifs/ipctl-output-formats.gif b/assets/gifs/ipctl-output-formats.gif new file mode 100644 index 00000000..b839d96e Binary files /dev/null and b/assets/gifs/ipctl-output-formats.gif differ diff --git a/assets/gifs/ipctl-version.gif b/assets/gifs/ipctl-version.gif new file mode 100644 index 00000000..b1853a57 Binary files /dev/null and b/assets/gifs/ipctl-version.gif differ diff --git a/assets/gifs/ipctl-workflow.gif b/assets/gifs/ipctl-workflow.gif new file mode 100644 index 00000000..884ec4a0 Binary files /dev/null and b/assets/gifs/ipctl-workflow.gif differ diff --git a/assets/gifs/tapes/ipctl-output-formats.tape b/assets/gifs/tapes/ipctl-output-formats.tape new file mode 100644 index 00000000..36fa95fe --- /dev/null +++ b/assets/gifs/tapes/ipctl-output-formats.tape @@ -0,0 +1,48 @@ +# Generated by gif-create +Output assets/gifs/ipctl-output-formats.gif + +# Terminal +Set Shell "bash" +Set Width 900 +Set Height 600 +Set FontSize 14 +Set FontFamily "MonoLisa, Menlo, monospace" +Set LineHeight 1.4 +Set LetterSpacing 0 +Set Padding 20 + +# Brand (Itential) +Set Theme {"name":"Itential","black":"#101625","red":"#FF6633","green":"#99CA3C","yellow":"#FFAC73","blue":"#1B93D2","purple":"#C5258F","cyan":"#E5F2FE","white":"#FFFFFF","brightBlack":"#414042","brightRed":"#FF6633","brightGreen":"#99CA3C","brightYellow":"#FFAC73","brightBlue":"#1B93D2","brightPurple":"#C5258F","brightCyan":"#E5F2FE","brightWhite":"#FFFFFF","background":"#101625","foreground":"#FFFFFF","selectionBackground":"#1B93D2","cursor":"#FFFFFF","cursorAccent":"#101625"} +Set BorderRadius 8 +Set MarginFill "#0D1018" +Set Margin 4 +Set WindowBar "Colorful" + +# Timing +Set TypingSpeed 40ms + +# Set bold pink prompt +Hide +Type `export PS1="$(printf '\e[1;38;2;197;37;143m> \e[0m')"` +Enter +Sleep 500ms +Type "clear" +Enter +Sleep 500ms +Show + +# Step 1: Default table output +Sleep 500ms +Type "ipctl get automations" +Enter +Sleep 3s + +# Step 2: JSON output +Type "ipctl get automations --output json" +Enter +Sleep 4s + +# Step 3: YAML output +Type "ipctl get automations --output yaml" +Enter +Sleep 4s diff --git a/assets/gifs/tapes/ipctl-version.tape b/assets/gifs/tapes/ipctl-version.tape new file mode 100644 index 00000000..5d9bb7bc --- /dev/null +++ b/assets/gifs/tapes/ipctl-version.tape @@ -0,0 +1,38 @@ +# Generated by gif-create +Output assets/gifs/ipctl-version.gif + +# Terminal +Set Shell "bash" +Set Width 800 +Set Height 500 +Set FontSize 14 +Set FontFamily "MonoLisa, Menlo, monospace" +Set LineHeight 1.4 +Set LetterSpacing 0 +Set Padding 20 + +# Brand (Itential) +Set Theme {"name":"Itential","black":"#101625","red":"#FF6633","green":"#99CA3C","yellow":"#FFAC73","blue":"#1B93D2","purple":"#C5258F","cyan":"#E5F2FE","white":"#FFFFFF","brightBlack":"#414042","brightRed":"#FF6633","brightGreen":"#99CA3C","brightYellow":"#FFAC73","brightBlue":"#1B93D2","brightPurple":"#C5258F","brightCyan":"#E5F2FE","brightWhite":"#FFFFFF","background":"#101625","foreground":"#FFFFFF","selectionBackground":"#1B93D2","cursor":"#FFFFFF","cursorAccent":"#101625"} +Set BorderRadius 8 +Set MarginFill "#0D1018" +Set Margin 4 +Set WindowBar "Colorful" + +# Timing +Set TypingSpeed 50ms + +# Set pink prompt, then clear screen +Hide +Type `export PS1="$(printf '\e[1;38;2;197;37;143m> \e[0m')"` +Enter +Sleep 500ms +Type "clear" +Enter +Sleep 500ms +Show + +# Recording +Sleep 500ms +Type "ipctl version" +Enter +Sleep 2s diff --git a/assets/gifs/tapes/ipctl-workflow.tape b/assets/gifs/tapes/ipctl-workflow.tape new file mode 100644 index 00000000..131b6f2a --- /dev/null +++ b/assets/gifs/tapes/ipctl-workflow.tape @@ -0,0 +1,48 @@ +# Generated by gif-create +Output assets/gifs/ipctl-workflow.gif + +# Terminal +Set Shell "bash" +Set Width 900 +Set Height 600 +Set FontSize 14 +Set FontFamily "MonoLisa, Menlo, monospace" +Set LineHeight 1.4 +Set LetterSpacing 0 +Set Padding 20 + +# Brand (Itential) +Set Theme {"name":"Itential","black":"#101625","red":"#FF6633","green":"#99CA3C","yellow":"#FFAC73","blue":"#1B93D2","purple":"#C5258F","cyan":"#E5F2FE","white":"#FFFFFF","brightBlack":"#414042","brightRed":"#FF6633","brightGreen":"#99CA3C","brightYellow":"#FFAC73","brightBlue":"#1B93D2","brightPurple":"#C5258F","brightCyan":"#E5F2FE","brightWhite":"#FFFFFF","background":"#101625","foreground":"#FFFFFF","selectionBackground":"#1B93D2","cursor":"#FFFFFF","cursorAccent":"#101625"} +Set BorderRadius 8 +Set MarginFill "#0D1018" +Set Margin 4 +Set WindowBar "Colorful" + +# Timing +Set TypingSpeed 50ms + +# Set bold pink prompt +Hide +Type `export PS1="$(printf '\e[1;38;2;197;37;143m> \e[0m')"` +Enter +Sleep 500ms +Type "clear" +Enter +Sleep 500ms +Show + +# Step 1: List projects +Sleep 500ms +Type "ipctl get projects" +Enter +Sleep 3s + +# Step 2: Describe a specific project +Type `ipctl describe project "Cisco IOS"` +Enter +Sleep 3s + +# Step 3: List automations +Type "ipctl get automations" +Enter +Sleep 3s diff --git a/assets/gifs/tapes/prompt.sh b/assets/gifs/tapes/prompt.sh new file mode 100644 index 00000000..d0a4b787 --- /dev/null +++ b/assets/gifs/tapes/prompt.sh @@ -0,0 +1 @@ +export PS1=$'\e[38;2;197;37;143m> \e[0m' diff --git a/assets/gifs/tapes/vhs-shell.sh b/assets/gifs/tapes/vhs-shell.sh new file mode 100755 index 00000000..57c258b8 --- /dev/null +++ b/assets/gifs/tapes/vhs-shell.sh @@ -0,0 +1,3 @@ +#!/bin/bash +export PS1=$'\e[38;2;197;37;143m> \e[0m' +exec bash --norc --noprofile -i diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 6d802053..d537d255 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -177,8 +177,7 @@ configuration file based on the profile name. The profile name can be passed to any command using the `--profile ` command line argument. A default profile can also be set in the configuration -file. See `default_profile` in the [Application Settings}(#Application -Settings) section for a description. +file. See `default_profile` in the [Application Settings](#application-settings) section for a description. ## Configuration options