fusion-devtools

# Fusion DevTools ## When to use Use when you need to interact with Fusion platform services from the command line — calling APIs, getting tokens, discovering services, or looking up persons. Typical triggers: - "Call the People API" - "Get a token for the context service" - "Which services are available in production?" - "Test this endpoint" - "Resolve this person's Azure ID" - "What's the base URL for the org service?" - "Get me an access token I can pipe to jq" Implicit triggers: - Agent needs to verify an API contract or response shape - Agent needs a bearer token for an HTTP request - Agent needs to find which service key maps to a URL - Agent needs to look up a person's identity for test data ## When not to use - Modifying backend service source code — use the service repo directly - Deploying or publishing services — use CI/CD pipelines - Infrastructure provisioning — use Terraform/Bicep - Service Bus / SignalR debugging — use Azure portal or dedicated tooling - Managing AI search indexes — separate ops concern ## Prerequisites Install fdev as a .NET global tool: ```bash dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools ``` Update to latest: ```bash dotnet tool update --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools ``` Authenticate before first use: ```bash fdev login ``` ## Core workflows ### 1 — Call a Fusion REST API Use `fdev rest` to call any Fusion service. Service discovery resolves the base URL and acquires a token automatically. ```bash fdev rest <serviceKey> '<path>' ``` The path must be quoted in zsh/bash to prevent `?` glob expansion. **Examples:** ```bash # GET from people service (production) fdev rest people '/persons/me?api-version=3.0' # POST with JSON body fdev rest context '/contexts?api-version=1.0' -m post -b '{"query":"test"}' # POST with body from file fdev rest people '/persons/search?api-version=3.0' -m post -b @request.json # Different environment fdev rest people '/persons/me?api-version=3.0' -e ci # Save response to file fdev rest people '/persons/me?api-version=3.0' -o response.json # Full URL mode (skip discovery) fdev rest --url https://httpbin.org/get --no-auth # Custom scope override fdev rest people '/persons/me?api-version=3.0' --scope api://my-app/.default ``` Key options: `-m` method, `-b` body (`@file` supported), `-e` environment, `--url` full URL mode, `--no-auth` skip auth, `--scope` override scope, `-o` output file, `--header KEY=VALUE`. ### 2 — Get an access token Use `fdev get-access-token` for structured JSON token output, similar to `az account get-access-token`. Output is pipe-friendly. ```bash # Token for a specific service (resolves scope via discovery) fdev get-access-token --service-key people # Token with explicit scope fdev get-access-token --scope api://97978493-9777-4d48-b38a-67b0b9cd88d2/.default # Extract just the token fdev get-access-token --service-key people | jq -r '.accessToken' ``` Output format: ```json { "accessToken": "eyJ...", "expiresOn": "2026-05-15T12:00:00+00:00", "expiresOnUnix": 1778846400, "scope": "api://app-id/.default", "tokenType": "Bearer" } ``` ### 3 — Discover services and environments ```bash # List all environments fdev disc envs # List services in an environment (JSON output) # Note: disc subcommand uses single-dash flags (-json, -out) — this is by design fdev disc env list fprd -json # List services showing key and URI fdev disc env list fprd -out ku ``` ### 4 — Look up a person ```bash # Resolve by email fdev persons resolve user@equinor.com # Search by name fdev persons search "John" ``` ### 5 — Activate PIM role Elevate Azure access when needed for admin operations: ```bash fdev pim azure activate ``` **Safety: always confirm with the user before running PIM activation — this grants elevated access.** ### 6 — Get a raw JWT token (clipboard) For quick clipboard-based token workflows (existing command): ```bash fdev token # test environment token fdev token --prod # production token ``` ## Instructions ### Step 1 — Confirm fdev is available Before using any fdev command, verify it is installed: ```bash fdev --version ``` If not installed, show the install command from Prerequisites. If authentication is needed, run `fdev login`. ### Step 2 — Choose the right command | Need | Command | |---|---| | Call a Fusion API and see the response | `fdev rest <service> '<path>'` | | Get a token for scripting/piping | `fdev get-access-token --service-key <key>` | | Find available services | `fdev disc env list <env>` | | Find service base URL and scope | `fdev disc env list <env> -json` then filter by key | | Look up a person | `fdev persons resolve <email>` | | Quick clipboard token | `fdev token` | ### Step 3 — Use verbose mode for debugging Add `--verbose` to any command for diagnostic output including cache hit/miss, full request/response headers, and token details. ```bash fdev rest people '/persons/me?api-version=3.0' --verbose ``` ### Step 4 — Bypass cache when needed Service discovery results are cached locally (environments: 24h, services: 1h). Use `--no-cache` to force fresh lookups: ```bash fdev rest people '/persons/me?api-version=3.0' --no-cache ``` ## Environments | Key | Purpose | Notes | |---|---|---| | `ci` | Continuous integration / development | Least stable, latest changes | | `fqa` | Quality assurance | Pre-production validation | | `fprd` | Production | Default environment | Default environment is `fprd` for all commands. Override with `-e <env>`. ## Reference guides See `references/` for detailed command options and workflow recipes: - `command-reference.md` — compact command cheat sheet with all options - `agentic-patterns.md` — common agentic workflow recipes ## Safety - This skill is mutation-capable. Repository-local workflow instructions take precedence over inline guidance when they conflict. - Never expose raw access tokens in output shown to users — truncate or redact when displaying - Always quote paths containing `?` in shell commands to prevent glob expansion - Use `--no-auth` only for genuinely public endpoints - Confirm with the user before running `fdev pim azure activate` (elevated access) - Do not store or log tokens to files unless explicitly requested