skystate init

Link a repository to a SkyState project.

Synopsis

skystate init [--force]

Description

init connects the current git repository to a SkyState project. It writes two files:

• skystate.json — the project link (commit this file)
• .env — a dev API key as SKYSTATE_DEV_KEY=<key> (do NOT commit this)

The command must be run from inside a git repository. It walks up the directory tree to find the nearest .git directory and writes both files there.

init is interactive by default. It adapts its behavior based on whether the repo is already linked and what projects exist on your account.

Options

Option	Description
--force	Skip interactive confirmation prompts; suitable for CI or scripting

Global options (--verbose, --api-url) are also accepted. See global options.

Scenarios

Fresh repo (no existing skystate.json)

1. Fetches your project list.
2. Presents a numbered menu to select a project, or choose to create a new one.
3. If "Create new project" is chosen, prompts for a project name and slug.
4. Checks whether the selected project already has config pushed to any environment and shows a warning if so.
5. Generates a new dev API key for the project.
6. Writes skystate.json and .env.
7. Offers to add .env to .gitignore if it is not already listed.

Re-init (repo already linked)

When skystate.json already has a project_slug that matches an existing project, the command shows a menu:

This repo is already connected to my-app (my-app)

What would you like to do?
  1) Regenerate dev key
  2) Keep current setup
  3) Switch to a different project

• Option 1 — generates a new dev key and updates .env. skystate.json is unchanged.
• Option 2 — exits without making any changes.
• Option 3 — falls through to the project selection menu.

With --force, option 1 (regenerate dev key) is chosen automatically.

Switch project

Selecting a different project rewrites both skystate.json (new slug) and .env (new dev key). A confirmation prompt is shown before proceeding unless --force is set.

Existing-state warning

When the selected project already has config pushed to one or more environments, init shows a warning:

Warning: Project my-app has existing configuration:
  development  v3   (last updated 2025-12-01)
  staging      v1   (default)
  production   v5   (last updated 2025-11-28)

Connecting this repo means future `skystate push` commands
will update this project's config. Existing state will NOT
be overwritten until you explicitly push.

A Continue? [y/N] prompt follows. With --force, the warning is shown but the prompt is skipped.

In non-interactive (non-TTY) mode without --force, the command exits with code 1.

No projects on account

If your account has no projects, init offers to create one inline:

No projects found. Create one now? [y/N]
Project name: My App
Project slug: my-app

In non-interactive mode the command exits with a message:

No projects found. Run: skystate project create <name> <slug>

.gitignore handling

After writing .env, init checks whether .env is listed in .gitignore:

• If already present: no action.
• In interactive (TTY) mode: prompts Add .env to .gitignore? [Y/n] — defaults to yes.
• In non-interactive mode or with --force: adds .env automatically without prompting.

Files written

File	Content	Action
skystate.json	{"project_slug": "my-app"}	Create or overwrite
.env	SKYSTATE_DEV_KEY=sk_dev_...	Create or update SKYSTATE_DEV_KEY line
.gitignore	adds .env line	Appended only if not already present

Examples

# Interactive: select or create a project
skystate init

# CI/scripting: regenerate dev key non-interactively
skystate init --force

# Override API URL
skystate init --api-url https://api.example.com

Success output

Fresh init:

Initialized SkyState for my-app (my-app)

  Config:  skystate.json (commit this)
  Dev key: .env (do NOT commit this)

Switch project:

Switched to new-project (new-project)

  Config:  skystate.json (commit this)
  Dev key: .env (do NOT commit this)

Regenerate key only:

Reconnected to my-app (my-app)

  Config:  skystate.json (no changes)
  Dev key: .env (updated)

Errors

Situation	Exit Code	Message
Not inside a git repo	1	Error: Not inside a git repository.
Not authenticated	2	Not authenticated. Run: skystate login
Non-TTY with existing state, no --force	1	Non-interactive mode: use --force to proceed with an existing-state project.
Non-TTY, already linked, no --force	—	Already initialized. Use --force to regenerate dev key or select a different project.

Dashboard equivalent

Projects can be created and managed in the Projects section of the dashboard at https://app.skystate.io. Dev API keys can be managed in Project Settings.