feat: persist the active environment in .env.local

[angeloashmore]

Resolves: #209

Description

Environments only had low-level controls: --env worked per command but nothing persisted it, so a dev had to remember which environment they were in and repeat the flag. This adds a persisted, shared active environment.

• prismic env list — list environments, including production, marking the active one
• prismic env set <name> — set the active environment (writes it to .env.local)
• prismic env unset — revert to production (removes it from .env.local)
• prismic env active — print the active environment

The active environment is stored as one framework-specific variable in .env.local, resolved by the adapter (NEXT_PUBLIC_PRISMIC_ENVIRONMENT, NUXT_PUBLIC_PRISMIC_ENVIRONMENT, VITE_PRISMIC_ENVIRONMENT). The CLI reads it as the default repository (after --env and --repo, before the prismic.config.json default). Generated Next.js and SvelteKit projects read the same variable natively; Nuxt reads it through @nuxtjs/prismic. The names match Slice Machine, so existing .env.local files stay compatible.

Checklist

• A comprehensive Linear ticket, providing sufficient context and details to facilitate the review of the PR, is linked to the PR.
• If my changes require tests, I added them.
• If my changes affect backward compatibility, it has been discussed.
• If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

How to QA ¹

In a Next.js or SvelteKit project with environments:

1. prismic env list — production is marked active.
2. prismic env set <environment> — writes the variable to .env.local; prismic env active reflects it, and content commands target it.
3. Run the dev server — the site reads the active environment.
4. prismic env unset — reverts to production.

---

Note

Medium Risk
Default repository resolution now affects many API commands (push/pull/sync, tokens, webhooks), so a stale .env.local could target the wrong environment; changes are local-dev focused and --repo/--env still override.

Overview
Adds a prismic env command group so local dev can keep a shared active environment instead of passing --env on every command.

env list, env set, env unset, and env active read and write a framework-specific variable in .env.local (NEXT_PUBLIC_PRISMIC_ENVIRONMENT, NUXT_PUBLIC_PRISMIC_ENVIRONMENT, or VITE_PRISMIC_ENVIRONMENT). Setting production removes the variable. Adapters expose repositoryEnvVar; new lib/env-file helpers update the file.

resolveRepositoryName() (active env from process.env / .env.local, else prismic.config.json) replaces getRepositoryName() as the default target for push/pull/sync/status and locale, preview, token, and webhook commands. --env / --repo still override per invocation.

Scaffolded Next.js and SvelteKit prismicio templates prefer the same env var for repositoryName, aligning the dev server with CLI and Slice Machine naming.

^{Reviewed by Cursor Bugbot for commit 4a511c6. Bugbot is set up for automated code reviews on this repo. Configure here.}

Footnotes

1. Please use these labels when submitting a review:
   ❓ #ask: Ask a question.
   💡 #idea: Suggest an idea.
   ⚠️ #issue: Strongly suggest a change.
   🎉 #nice: Share a compliment. ↩

[cursor]

Active env breaks --env resolution

Medium Severity

The parentRepo variable, now resolved by resolveRepositoryName(), can incorrectly default to an active environment's domain from .env.local instead of the production repository. This happens when --repo is not provided, causing resolveEnvironment to use the wrong base repository and potentially fail or target incorrect environments for prismic push and prismic pull.

Additional Locations (1)

• src/commands/pull.ts#L28-L36

 

^{Reviewed by Cursor Bugbot for commit 8820fb6. Configure here.}

[cursor]

Empty active env breaks repo

Medium Severity

resolveRepositoryName uses nullish coalescing, so an empty NEXT_PUBLIC_PRISMIC_ENVIRONMENT (or adapter equivalent) in .env.local is treated as the repository name instead of falling back to prismic.config.json, leading to invalid API hosts and broken commands.

Additional Locations (1)

• src/environments.ts#L49-L54

 

^{Reviewed by Cursor Bugbot for commit 8820fb6. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b7a5949. Configure here.}

[cursor]

--env uses active staging parent

Medium Severity

When --env is used without --repo and a staging environment is active, the parentRepo incorrectly resolves to the staging domain. This causes environment resolution to query the staging repository's API instead of the production one, leading to incorrect or failed lookups.

 

^{Reviewed by Cursor Bugbot for commit b7a5949. Configure here.}