# ivar feature > The feature lifecycle on the command line — create, promote, demote, rebase, integrate, close and prune. Source: https://ivar.run/docs/reference/feature import { Callout } from 'fumadocs-ui/components/callout'; import { Step, Steps } from 'fumadocs-ui/components/steps'; A **feature** is a name, a branch, and the set of repos that branch exists in. It is the unit `ivar` uses to decide what an agent may write to and what gets delivered together. ## Create a feature ```sh ivar feature create billing-currency ``` The name is one path segment, unique in the hall, and becomes the branch name. When the branch has to be spelled differently than the feature — `feat/login`, say — pass `--branch`: ```sh ivar feature create login --branch feat/login ``` `--base` sets the branch new promotions start from, per repo. Left off, each repo starts from its own default branch. `create` records the feature and nothing else. Repos join it one at a time through `promote`, which is what makes scope an explicit decision rather than a guess made up front. ## Promote the repos it touches ```sh ivar feature promote billing-currency api ivar feature promote billing-currency web ``` Promotion cuts the feature's branch in that repo and materialises its worktree. A branch that already exists is adopted as it is; one that does not is created off the repo's effective base. `--base` overrides that start point for a single repo. Everything you did not promote stays on its default branch — and, inside a session, stays read-only. That is the mechanism described in [the guard](/docs/reference/session#the-guard). ## When scope moves Scope is rarely right the first time. It is normal to find, halfway through, that the change reaches one repo further: Promote the repo you now need. The worktree appears and the guard lifts for it. ```sh ivar feature promote billing-currency shared ``` Or take one back out. `demote` removes the repo from the feature and leaves its worktree on disk, so nothing you already wrote is lost. ```sh ivar feature demote billing-currency infra ``` ## Inspect ```sh ivar feature list # every feature and how far it got ivar feature status billing-currency # one feature, repo by repo ``` `status --recursive` reports a feature's whole subtree. ## Keep up with the base ```sh ivar feature rebase billing-currency ``` Every promoted worktree is rebased onto its effective base. A dirty worktree is skipped rather than stashed, and a conflict is aborted and reported — `ivar` will not leave you inside a half-finished rebase. ## Subfeatures A feature can be created under another one, deriving its base from the parent's branch instead of a repo default: ```sh ivar feature create billing-currency-ui --parent billing-currency ``` `ivar feature integrate` lands a child into its immediate parent, leaves first, one promoted repo at a time — durable and resumable. The integration policy (`--via pr` or `local`, `--strategy squash`, `merge` or `rebase`) is persisted when the feature is created; after the first receipt it is frozen. `ivar feature reparent` moves a still-pristine child under a different parent. It is refused the moment anything real exists under the feature — a promotion, a plan, a session, a receipt or a descendant. ## Finish up ```sh ivar feature close billing-currency # stop executors, record the outcome ivar feature delete billing-currency # worktrees, .ivar/ directory and plans ivar feature prune # drop features already merged into their default branches ``` `close` is idempotent — closing a closed feature does nothing. `delete` refuses if anything under the feature directory cannot be removed, and keeps the feature record so you can retry.