Installation

This page covers all the ways to install and access SkyState tooling.

---

Packages

Tool	Package
CLI	skystate
Core SDK	@skystate/core
React SDK	@skystate/react

---

CLI

The SkyState CLI (sky) is the primary tool for pushing public state, managing projects, and authenticating from the terminal. Use public state for application config, feature flags, public settings, and client-visible catalog or inventory values.

Requirements

• Node.js 20 or later
• npm 8 or later (or any compatible package manager)

Global Install

npm install -g skystate

Project-Local Install

If you prefer to pin the CLI version per project, install the same skystate package as a dev dependency.

Then run it via npx or through a package.json script:

npx sky --version

{
  "scripts": {
    "push:dev": "sky state public push --project my-app --file config.json --env development"
  }
}

Updating

npm update -g skystate

---

SDKs

SkyState ships two JavaScript/TypeScript SDK packages.

@skystate/core

A framework-agnostic client for Node.js, browser, and any JavaScript environment. Use this for non-React apps, server-side usage, or when you want to build your own integration layer.

npm install @skystate/core

Basic Usage

import { createSkyStateClient } from '@skystate/core';

const client = createSkyStateClient({
  account: 'acc_example',
  project: 'my-app',
  environment: 'production',
});

await client.init();

// Read a single key with a fallback default
const maintenance = client.publicState.get('maintenance', { enabled: false });

TypeScript Support

@skystate/core ships full TypeScript type definitions. No @types/ package is required.

@skystate/react

React hooks and context provider built on top of @skystate/core. Designed for React 18+.

npm install @skystate/react

Setup

Wrap your root component with SkyStateProvider:

// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { SkyStateProvider } from '@skystate/react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <SkyStateProvider
      account="acc_example"
      project="my-app"
      environment={import.meta.env.PROD ? 'production' : 'development'}
    >
      <App />
    </SkyStateProvider>
  </React.StrictMode>
);

Public state loads anonymously and is useful for application config, feature flags, public settings, and client-visible catalog or inventory values. User state requires users to sign in with useAuth().loginWithRedirect().

Hooks

import { usePublicState } from '@skystate/react';

function AnnouncementBanner() {
  const { value: banner } = usePublicState('banner', {
    enabled: false,
    text: '',
  });
  const publicState = usePublicState();

  if (publicState.status === 'loading' || !banner.enabled) return null;

  return <div className="banner">{banner.text}</div>;
}

The keyed usePublicState hook returns:

Property	Type	Description
value	T	The resolved value. Returns the fallback until public state is ready, when the key is absent, or when the stored value is null.

Use the no-argument usePublicState() hook separately for loading and error state:

Property	Type	Description
status	'idle' | 'loading' | 'ready' | 'error'	Current public-state subsystem status.
error	SkyStateError	Present only when status === 'error'.

---

Environment Variables

In Node.js / Server Environments

For server-side API access, generate a project API key from the console and send it only from trusted backend code:

# .env
SKYSTATE_API_KEY=your-api-key-here

Server-side credentials should never be exposed to the browser bundle. Always use environment variables that are not prefixed with VITE_ or NEXT_PUBLIC_.

---

Console

The SkyState console is a web application - no installation required.

Access it at: https://console.skystate.io

Sign in to access the console. The console provides:

• A project overview showing all your projects and their environments.
• A Public state editor with syntax highlighting and diff view for application config, feature flags, settings, and inventory-style values.
• Version history with the ability to view and restore any past version.
• Usage page showing your API request counts and billing status.
• Settings for managing dev API keys, account details, and subscription.

Browser Requirements

The console works in any modern browser. Chrome, Firefox, Safari, and Edge are all supported. JavaScript must be enabled.

---

CI/CD Integration

To use the CLI in CI pipelines, provide credentials via environment variables instead of running sky login interactively.

Using an API Key

Run sky login once locally to authenticate (interactive, PKCE). For CI or other non-interactive use, set SKYSTATE_API_KEY to a project API key created via sky project keys create. Add that value as a repository secret in your CI provider:

# GitHub Actions example
- name: Push public state
  env:
    SKYSTATE_API_KEY: ${{ secrets.SKYSTATE_API_KEY }}
  run: |
    npm install -g skystate
    sky state public push --project my-app --file config.json --env staging --yes

The CLI reads SKYSTATE_API_KEY automatically - no sky login step is needed when this variable is set.

Non-Interactive Mode

Pass --yes to skip confirmation prompts in scripts:

sky state public push --project my-app --file config.json --env production --yes

---

Uninstalling

Remove the CLI

npm uninstall -g skystate

Remove Stored Credentials and Config

rm -rf ~/.config/skystate

This removes your stored token and CLI config. You will need to run sky login again after reinstalling.