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:

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 user@equinor.com

# 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

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

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

Changelog

0.1.0 - 2026-05-29

minor

• #176 `7da00f3` Thanks @alftore! - Add fusion-devtools skill for Fusion DevTools CLI (fdev)

Covers REST API calls, token acquisition, service discovery, person lookup, PIM activation, and environment mapping.

Agentic workflow patterns

Common recipes for coding agents using fdev in automated workflows.

Pattern 1 — Verify API response shape

When an agent needs to confirm the actual response structure from a Fusion API:

# Fetch a real response and inspect its structure
fdev rest people '/persons/me?api-version=3.0' | jq 'keys'

# Get full response with headers for debugging
fdev rest people '/persons/me?api-version=3.0' --verbose

Use case: before generating client code or types, verify the actual API contract matches expectations.

Pattern 2 — Get a token for external tools

When an agent needs a bearer token to pass to curl, httpie, or another HTTP client:

Prefer fdev rest with --url when possible — it handles tokens internally without exposing them. Use the variable approach only when another tool must make the HTTP call.

# Extract token for use in other commands (short-lived, local shell variable only)
TOKEN=$(fdev get-access-token --service-key people | jq -r '.accessToken')
BASE_URL=$(fdev disc env list fprd -json | jq -r '.[] | select(.key=="people") | .uri')

# Use with curl
curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/persons/me?api-version=3.0"

Use case: agent needs to call an endpoint not yet in service discovery, or needs fine-grained control over the HTTP request.

Pattern 3 — Discover service base URL

When an agent needs to construct URLs for documentation or configuration:

# Find the base URL for a service
fdev disc env list fprd -json | jq '.[] | select(.key=="people") | .uri'

# List all service keys
fdev disc env list fprd -json | jq '.[].key'

Use case: generating app.config.ts service client registrations, updating documentation with correct endpoints.

Pattern 4 — Resolve person identity

When an agent needs a person's Azure Object ID for test data or API calls:

# Resolve email to person details
fdev persons resolve user@equinor.com

# Search by name when email is unknown
fdev persons search "John Smith"

Use case: setting up test fixtures, looking up managers/owners, populating request bodies that require person identifiers.

Pattern 5 — Test across environments

When validating that an API behaves consistently across environments:

# Compare responses across environments
fdev rest people '/persons/me?api-version=3.0' -e ci
fdev rest people '/persons/me?api-version=3.0' -e fqa
fdev rest people '/persons/me?api-version=3.0' -e fprd

Use case: debugging environment-specific issues, verifying deployments.

Pattern 6 — POST with request body from file

When an agent generates a request payload and needs to send it:

# Write payload to temp file, send, then clean up
TMPFILE=$(mktemp /tmp/fdev-body.XXXXXX.json)
cat > "$TMPFILE" << 'EOF'
{
  "searchString": "test",
  "top": 5
}
EOF

fdev rest people '/persons/search?api-version=3.0' -m post -b @"$TMPFILE"
rm -f "$TMPFILE"

Use case: complex request bodies that are easier to construct as files than inline JSON.

Pattern 7 — Chain discovery with token for scripting

Full scripted flow: discover service, get token, make authenticated calls:

# Get service info as JSON
SERVICE_INFO=$(fdev disc env list fprd -json | jq '.[] | select(.key=="org")')
BASE_URL=$(echo "$SERVICE_INFO" | jq -r '.uri')

# Get token for that service
TOKEN=$(fdev get-access-token --service-key org | jq -r '.accessToken')

# Make multiple calls with the same token
curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/projects?api-version=3.0" | jq '.value | length'

Use case: batch operations, scripted validation, integration testing.

Safety reminders

• Redact tokens: when showing output to users, truncate or mask accessToken values
• Quote paths: always single-quote paths containing ? or & to prevent shell expansion
• Confirm PIM: ask user before running fdev pim azure activate
• Prefer --service-key: over hardcoded scopes — service keys adapt to environment changes
• Use --verbose: for debugging, not in final agent output — it contains sensitive headers

Command reference

Compact reference for all fdev commands relevant to agentic workflows.

Authentication

fdev login                    # Interactive Azure AD login (browser)
fdev login --client-secret    # Service principal login

REST API calls

fdev rest <serviceKey> '<path>' [options]
fdev rest --url <fullUrl> [options]

Token acquisition

fdev get-access-token [options]

Output: JSON with accessToken, expiresOn, expiresOnUnix, scope, tokenType.

fdev token [--prod]           # Quick token to clipboard (test env default)

Service discovery

fdev disc envs                         # List environments
fdev disc env list <env>               # List services in environment
fdev disc env list <env> -json         # JSON output
fdev disc env list <env> -out ku       # Show key + URI columns

Person resolution

fdev persons resolve <email>           # Resolve by email or UPN
fdev persons search "<name>"           # Search by name

PIM access elevation

fdev pim azure activate               # Activate eligible Azure PIM role

Safety: always confirm with user before running PIM activation.

Common service keys (examples — verify with discovery)

These are typical service keys. Keys may change as services are added, renamed, or retired. Always verify with fdev disc env list <env> -json | jq '.[].key'.

Use fdev disc env list fprd -json | jq '.[].key' to get the full list of service keys for an environment.

Environment mapping

Global options