@shipdit/cli 0.5.0 → 0.7.0

package/README.md

@@ -1,35 +1,123 @@
 # @shipdit/cli
 
-Command-line interface for shipd config-as-code workflows.
+Command-line interface for managing [shipd](https://useshipd.com) feature flags
+and targeting rules from TypeScript or Go config files.
 
-```bash
-pnpm --filter @shipdit/cli build
-shipd login # approve org → project → environment in the browser
+## Install
+
+Requires Node.js 22.12+.
+
+```sh
+npm install -g @shipdit/cli
+```
+
+## Get started
+
+```sh
+shipd login
 shipd pull
 shipd diff
-shipd push --yes
-shipd types gen
+shipd push
+```
+
+`shipd login` opens the browser to select your organization, project, and
+environment, then stores a scoped management API key locally. `shipd pull`
+downloads published flags into a config file and generates types. Review the
+generated source, edit your definitions, then use `shipd diff` and `shipd push`
+to preview and apply changes.
+
+If you already have a local config, commit or back it up before pulling: pull
+regenerates source and replaces comments and helper code.
+
+## TypeScript projects
+
+Install the SDK in your application:
+
+```sh
+npm install shipdit
 ```
 
-`shipd login` stores a scoped management API key. Use `SHIPD_API_KEY` for CI — keys carry org/project/environment metadata.
+Create `shipd.config.ts` in your project root:
+
+```ts
+import { defineFlags } from 'shipdit/config';
+
+export default defineFlags({
+  'new-checkout': {
+    type: 'boolean',
+    default: false,
+    description: 'Redesigned checkout flow',
+  },
+});
+```
+
+Run `shipd diff` and `shipd push` to sync it. Push and pull generate
+`src/generated/flags.ts`; `shipd types gen` regenerates types locally without
+syncing. Import the generated `FlagDefinitions` type into your SDK client for
+typed flag keys and return values.
 
 ## Go projects
 
-The CLI reads `shipd.config.go` directly. Declare an exported
-`var Config = config.ShipdConfig{...}` using
-`github.com/alasti-company/useshipd.com/sdks/go/config`. Go 1.23+ and Node.js 22.12+
-are needed for CLI commands; the application runtime only needs Go.
+Install the Go SDK in your application module:
 
-```bash
-shipd diff
-shipd push
-shipd types gen
-shipd pull
+```sh
+go get github.com/alasti-company/useshipd.com/sdks/go
 ```
 
-Go input automatically selects Go output in `internal/flags/flags_gen.go`.
-Generation emits per-flag accessors, key and variant constants, and `Defaults()`.
-Pull writes Go definitions back to `shipd.config.go`. No JSON flag file is needed.
-The definition file is evaluated on its own inside the Go module: imports and
-helpers declared in that file work; sibling files are not loaded. Do not define
-`main` in it. See `examples/go-examples` for a complete example.
+Go 1.23+ is required. Create `shipd.config.go` using your directory's package name:
+
+```go
+package main
+
+import "github.com/alasti-company/useshipd.com/sdks/go/config"
+
+var Config = config.ShipdConfig{
+    "new-checkout": {
+        Type:        "boolean",
+        Default:     false,
+        Description: "Redesigned checkout flow",
+    },
+}
+```
+
+The CLI reads the exported `Config` directly and generates Go accessors in
+`internal/flags/flags_gen.go`. Run the same `shipd diff`, `shipd push`,
+`shipd pull`, and `shipd types gen` commands as for TypeScript. The application
+runtime only needs Go; Node.js is needed to run the CLI.
+
+Keep the definition file self-contained. Imported packages and helpers declared
+in that file work; sibling files are not loaded. Do not define `main` in it.
+Pull regenerates `shipd.config.go` and its accessors.
+
+## Targeting rules and sync
+
+Add optional `targeting` to manage an environment's enabled state, ordered rules,
+and fallthrough. Omitting it preserves dashboard rules and enabled state;
+setting `rules: []` explicitly clears rules. Optional per-flag `traits`
+declarations describe the accepted targeting inputs.
+
+Targeting changes apply to the selected environment. Production targeting uses
+the dashboard draft and approval workflow. Flag definitions and trait contracts
+are shared across environments and update project-wide immediately.
+
+Pull reads published state. The CLI detects conflicting targeting edits using a
+local sync baseline; review conflicts before using a force option. Ignore
+`**/.shipd/sync/` in version control to cover nested projects too.
+
+## CI
+
+Set `SHIPD_API_KEY` to a management API key with permission for your target
+project and environment. Keep it in your CI secret store. Use `--yes` for
+non-interactive pushes:
+
+```sh
+shipd diff --env development
+shipd push --env development --yes
+```
+
+SDK keys used by application clients do not authorize CLI management operations.
+Run `shipd --help` or `shipd <command> --help` for available commands and options.
+
+See the [CLI reference](https://docs.useshipd.com/reference/cli),
+[TypeScript and Go configuration examples](https://docs.useshipd.com/reference/config),
+and [sync conflict guide](https://docs.useshipd.com/config-as-code/conflicts).