{"name":"--environment","slug":"environment","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Create a new cloud session that runs on the [self-hosted environment](\/docs\/en\/self-hosted-environments) with the given ID. Environment IDs start with `ccpool_`. See [`--environment` dispatch behavior](\/docs\/en\/self-hosted-environments-testing#environment-dispatch-behavior) for dispatch behavior and the flag combinations it rejects. Requires Claude Code v2.1.224 or later","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":null,"removed_in":null,"in_current_build":false,"newest_mined":"2.1.308","builds":0,"mined_builds":149,"first_cited":{"version":"2.1.224","released_at":"2026-08-07 01:36:32","spans":7}},"aliases":[],"entries":[{"version":"2.1.295","anchor":"environment-accepts-env-ids-and-names-but-only-a-pool-id","heading":"--environment now reads environment IDs and names, but still only runs pool IDs","line":"`--environment` now recognises IDs starting with env_ and plain names, but only IDs starting with ccpool_ actually work so far","released_at":"2026-10-08 18:22:58","reason":"found in this entry's text"},{"version":"2.1.288","anchor":"headless-environment-error-names-the-actual-flag","heading":"Headless cloud session errors now name the flag you actually used","line":"Errors when starting a cloud session without the interactive screen now name the flag you used instead of always saying `--environment`","released_at":"2026-10-02 18:30:40","reason":"found in this entry's text"},{"version":"2.1.288","anchor":"cloud-environment-error-text-now-chosen-by-a-helper","heading":"Errors for conflicting cloud session options can name a different option","line":"Errors about conflicting --cloud or --environment options no longer always name --environment or always start with Error:","released_at":"2026-10-02 18:30:40","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"rule-conflict-wording-and-claudemd-loading-simplified","heading":"CLAUDE.md nested loading and an --environment error message reworked","line":"The code that loads nested CLAUDE.md files was simplified, and the error for combining `--environment` with `--cloud` is now built in parts","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"headless-cloud-launch-refuses-sessions-not-recognized-as-clo","heading":"Headless cloud sessions stop early if they were not started as cloud sessions","line":"A cloud session without the interactive screen now stops with an error if Claude Code did not recognise it as a cloud launch at start-up","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"no-monorepo-supplies-a-default-environment-fast-path-ad","heading":"Cloud sessions without a monorepo get a default environment","line":"With the no-monorepo option, `--environment` now falls back to a default environment ID, and its conflict error messages have been reworded","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"nomonorepo-option-threaded-into-pool-based-remote-session-cr","heading":"Cloud sessions created with --environment pass on a no-monorepo option","line":"Creating a cloud session with --environment now passes a no-monorepo option along with the environment ID","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"cloud-launch-refuses-when-it-would-need-the-keyboard","heading":"--cloud stops early when it would need a keyboard it can't read","line":"If `--cloud` would open a session in your terminal but there is no keyboard to read from, Claude Code now exits with an error before creating it","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"},{"version":"2.1.285","anchor":"remote-session-creation-passes-disallowed-tools","heading":"Cloud sessions started with --environment prepare to pass on blocked tools","line":"Creating a cloud session with --environment can now send a list of blocked tools, though that list is always empty in this build","released_at":"2026-09-29 17:32:09","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"hidden-claude-p-cloud-headless-cloud-print-path-added","heading":"Hidden claude -p --cloud headless cloud-print path added, but compiled off","line":"Code for a headless `claude -p --cloud` run is added, but the switch that enables it returns false, so no one can use it in 2.1.281","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text"}],"entries_total":24,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"api","path":"cli-sdks-libraries\/cli\/scripting","title":"scripting","documented":false},{"source":"api","path":"cli-sdks-libraries\/cli\/using","title":"using","documented":false},{"source":"api","path":"managed-agents\/budgets","title":"budgets","documented":false},{"source":"api","path":"managed-agents\/define-outcomes","title":"DCF Model Rubric","documented":false},{"source":"api","path":"managed-agents\/environments","title":"environments","documented":false},{"source":"api","path":"managed-agents\/files","title":"files","documented":false},{"source":"api","path":"managed-agents\/github","title":"github","documented":false},{"source":"api","path":"managed-agents\/mcp-connector","title":"mcp-connector","documented":false},{"source":"api","path":"managed-agents\/multiagent-orchestration","title":"multiagent-orchestration","documented":false}],"docs_total":13,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/environment","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}