fusion-devtools

name	fusion-devtools
description	Use Fusion DevTools CLI (fdev) for API testing, token acquisition, service discovery, and person lookup during development. USE FOR: calling Fusion REST APIs, getting access tokens as JSON, discovering services and environments, resolving persons, PIM role activation. DO NOT USE FOR: modifying backend service code, deploying services, infrastructure changes, CI/CD pipeline configuration, or Service Bus operations.
license	MIT
compatibility	Requires fdev installed as a .NET global tool (dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools). Requires Azure AD login (fdev login). Works best alongside fusion-backend-dev for understanding API contracts before calling them.
metadata	{"version":"0.1.1","status":"active","owner":"@equinor/fusion-core","tags":["fusion","devtools","cli","rest-api","token","service-discovery","debugging","testing"]}

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:

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:

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:

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.

fdev rest <serviceKey> '<path>'

The path must be quoted in zsh/bash to prevent ? glob expansion.

Examples:

# 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.

# 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:

{
  "accessToken": "eyJ...",
  "expiresOn": "2026-05-15T12:00:00+00:00",
  "expiresOnUnix": 1778846400,
  "scope": "api://app-id/.default",
  "tokenType": "Bearer"
}

3 — Discover services and environments

# 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

# Resolve by email
fdev persons resolve [e-mail]

# Search by name
fdev persons search "John"

5 — Activate PIM role

Elevate Azure access when needed for admin operations:

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):

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:

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.

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:

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