---
name: "CLI --port flag with project.toml persistence"
---

# Story 399: CLI --port flag with project.toml persistence

## User Story

As a developer, I want to set the server port via a --port CLI flag that persists to project.toml, so that I don't have to remember an environment variable on every run.

## Acceptance Criteria

- [ ] `storkit --help` shows a `--port` option
- [ ] `storkit --port 4000` starts the server on port 4000
- [ ] After first run with `--port`, the port is saved to `project.toml`
- [ ] On subsequent runs without `--port`, the port from `project.toml` is used
- [ ] CLI `--port` overrides the value in `project.toml`
- [ ] Default port is 3001 when neither `--port` nor `project.toml` port is set
- [ ] `STORKIT_PORT` env var is removed — no longer read or respected
- [ ] `.storkit_port` lock file mechanism is removed (`write_port_file` / `remove_port_file`)

## Out of Scope

- Docker compose changes (can update `STORKIT_PORT` references separately)
- Adding other CLI flags beyond `--port`

## Technical Notes

Port resolution priority: `--port` flag > `project.toml` `port` field > default 3001

The port should be written to `project.toml` on startup so subsequent runs remember it. Use the existing `config.rs` / `ProjectConfig` struct — add a `port` field.
