Authentication Profile Management

🔐 Authentication Profile Management

PACX supports three complementary strategies for telling each command which Dataverse environment to connect to. Each strategy builds on the previous one, addressing its shortcomings. Understanding all three — and when to reach for each — lets you keep multiple environments and projects in flight without constantly reconfiguring things.

🌍 Strategy 1 — Global default profile (pacx auth select)

⚙️ How it works

Every PACX installation maintains a single global settings file (stored in %appdata%\PACX\) that records all authentication profiles and which one is currently the default. When you run any command that needs a Dataverse connection, PACX reads this file and uses the default profile.

# Create a profile
pacx auth create --name myorg --environment https://myorg.crm4.dynamics.com

# Make it the default — all subsequent commands target myorg-dev
pacx auth select --name myorg

# Run a command — no need to specify a profile
pacx table create --name myentity ...

This is designed to mimic the pattern used by PAC CLI: authenticate once, then all commands inherit that context until you change it.

✅ Pros

#	Advantage
1	Simple. One command to switch context, no per-folder setup required.
2	Script-friendly. Set the default at the top of a deployment script; every command in the script automatically targets the right environment.
3	Zero friction for developers who always work against a single environment.

❌ Cons

#	Disadvantage
1	Global state. A single terminal-level switch affects every command in every shell on the machine. If you open two terminals and set different defaults in each, they will conflict — pacx auth select writes to a shared file, not to the current session.
2	Error-prone in multi-project work. Switching from project-a-dev to project-b-staging and forgetting to switch back is a common mistake that can push changes to the wrong environment.
3	Invisible to source control. Nothing in the repository indicates which environment should be used; the information lives only on the developer's machine.
4	No parallelism. You cannot reliably run two PACX commands targeting different environments at the same time.

---

📂 Strategy 2 — Project-level profile (.pacxproj file)

⚙️ How it works

The pacx project init command creates a .pacxproj file in the current directory. This JSON file records the authentication profile (and optionally a default solution) that should be used for any PACX command that runs from that folder or any of its subfolders.

# Inside C:\work\project-a
pacx project init --conn "project-a-dev" --solution ProjectA_Solution

This creates C:\work\project-a\.pacxproj:

{
	"Version": "1.0",
	"IsSuspended": false,
	"AuthProfileName": "project-a-dev",
	"SolutionName": "ProjectA_Solution"
}

From this point on, running any PACX command inside C:\work\project-a\ (or any subfolder) automatically uses project-a-dev, without touching the global default.

# Inspect what the current folder resolves to
pacx project info

# Temporarily stop using the project file (global default kicks back in)
pacx project suspend

# Re-enable the project file
pacx project resume

pacx auth list marks the project-bound profile with a + (shown in green) to make the active resolution visible at a glance.

🔢 Resolution priority

When a command looks for a connection to use, the lookup order is:

1. Project-level profile (.pacxproj in the current folder tree)
2. Global default (pacx auth select)

✅ Pros

#	Advantage
1	Folder-scoped context. Each repository or workspace can have its own environment binding stored inside the project directory.
2	Source-controllable. Commit .pacxproj to the repository so every contributor automatically targets the right environment when they cd into the project folder.
3	Works in parallel. Two terminals, two project folders, two different environments — no conflicts.
4	Suspend / resume. You can temporarily lift the project override without deleting the file.
5	Solution binding. The .pacxproj file also pins the default solution, eliminating the need to pass --solution to every command.

❌ Cons

#	Disadvantage
1	Requires filesystem setup. Someone must run pacx project init in the right folder. On a fresh clone there is nothing until that step is done.
2	Folder-boundary limitation. If you need to run a one-off command against a different environment from inside a project folder, you must either suspend the project or use strategy 3.
3	Per-machine profiles still needed. The .pacxproj references a profile name; each machine must have a profile with that exact name registered via pacx auth create.

---

⚡ Strategy 3 — Per-invocation override (--environment / -env)

Implemented in response to issue #189.

⚙️ How it works

Any PACX command accepts a global --environment flag (short form: -env) that overrides both the global default and any .pacxproj binding for that single invocation. No files are written or changed.

# Run one command against a different environment, then return to normal
pacx table list --environment "my-staging-org"

# Works equally well with the environment URL
pacx table list --environment "https://myorg.crm4.dynamics.com"

# Combine with --interactive to open a session pinned to a specific environment
pacx --environment "my-staging-org" --interactive
# or with the short form
pacx -env "my-staging-org" --interactive

The value passed to --environment / -env is resolved as follows:

1. Profile name match (case-insensitive) — the value is compared against stored profile names.
2. URL match — if no name matches, the value is compared against the environment URL stored in each profile's connection string (trailing slashes and casing are normalised).

pacx auth list marks the currently-overridden profile with a ! (shown in dark yellow).

🔢 Resolution priority (full picture)

Priority	Source	Mechanism
1 (highest)	--environment / -env flag	Per-invocation; not persisted
2	.pacxproj file	Folder-scoped; committed to source control
3 (lowest)	pacx auth select	Global; stored in %appdata%\PACX\

✅ Pros

#	Advantage
1	Zero setup. No files, no folders, no configuration changes. One flag, one command.
2	Non-destructive. The global default and any project binding are never touched.
3	Scriptable one-liners. CI/CD pipelines can pass -env without managing any persistent state.
4	Interactive session pinning. pacx -env <profile> --interactive starts an interactive session permanently bound to the specified environment, making it easy to work in a second environment alongside an open project session.
5	Name or URL. You can reference environments by profile name or by URL — useful in scripts that only know the environment endpoint.

❌ Cons

#	Disadvantage
1	Single-invocation only. You must pass the flag on every command; there is no "sticky" override for a shell session.
2	Verbose for long workflows. If you need to run twenty commands against the same non-default environment, repeating -env on each is tedious — use strategy 2 instead.
3	Profile must exist. The resolved profile name (or URL) must already be registered on the machine; --environment does not create a connection.

🧭 Choosing the right strategy

Scenario	Recommended strategy
Single-environment developer	Global default (auth select)
Team working on a shared repository	Project file (.pacxproj) committed to the repo
Two parallel workstreams in different folders	Two .pacxproj files, one per folder
Deployment / CI scripts	Project file (.pacxproj) committed to the repo
Quick one-off command against a different environment	--environment flag
Multi-environment interactive exploration	--environment with --interactive

👁️ Visualising the active profile

pacx auth list shows all registered profiles and annotates the ones currently in effect:

  myorg-dev*+          https://myorg.crm4.dynamics.com
  myorg-staging!       https://myorg-staging.crm4.dynamics.com
  myorg-prod           https://myorg.crm4.dynamics.com

Marker	Colour	Meaning
*	Cyan	Global default (set by pacx auth select)
+	Green	Project-level default (set by .pacxproj)
!	Dark yellow	Active --environment override for this command

When multiple markers apply to the same profile, all are shown (e.g. *+ means both the global default and the project binding point to the same profile).