Last updated: June 20, 2026 · 6 min read

What is the KWS CLI?

The KWS CLI is a small command-line tool that lets you deploy static websites and AI projects to Katika Web Services straight from your terminal. Think of it as your shortcut for sending code to your dashboard without opening a browser. It is the same workflow developers use with Vercel or Netlify, adapted for the KWS hosting platform.

Common things you can do with it:

Deploy a folder from your computer to a live URL in seconds.
Read the build log from your most recent deployment.
List the projects you own and open any of them in your browser.

Step 1: Install the CLI

The CLI ships inside the main katikaws-new repository. Until we publish it to npm, clone the repo, install dependencies, and link globally:

Run in your terminal:

git clone https://github.com/BisonGuru/katikaws-new.git
cd katikaws-new/cli
npm install
npm install -g .

The first npm install pulls runtime dependencies (archiver and friends). The second one links the kws binary globally so you can run it from any folder. Confirm it works:

kws --version
which kws

If you get kws: command not found, your npm global bin/ directory is not on your PATH. Run npm config get prefix and add <that-path>/bin to your shell config (~/.zshrc or ~/.bashrc).

If kws --version errors with Cannot find module 'archiver', your clone is stale (predates the archiver dependency) or you skipped npm install. Recover with: cd ~/katikaws-new && git pull && cd cli && rm -rf node_modules package-lock.json && npm install && npm install -g .

Step 2: Sign in with a Personal Access Token

The CLI talks to KWS using a Personal Access Token (PAT) rather than your dashboard password. You mint a token once, paste it into kws login, and the CLI uses it for every command after that.

Where to get a token: /dashboard → Settings → API → click Create Token.

When you create the token, pick at minimum these three scopes. Without all three, certain commands will silently fail with a confusing error:

deployments:write — required for kws deploy.
deployments:read — required for kws logs and for the deploy progress poll inside kws deploy.
projects:read — required for kws projects and slug lookups.

Copy the token (it is only shown once) and run:

kws login

Paste the token when prompted. It saves to ~/.kwsrc with file permissions 0600 so only you can read it.

If you ever lose the token or revoke it, just run kws login again with a new one.

Step 3: Deploy a folder

kws deploy zips up the current directory (skipping node_modules, .git, and dotfiles), uploads it to KWS, and polls until the deploy is live.

Deploy a static site:

cd ~/sites/my-static-site
kws deploy

You will see progress messages stream by — upload, build, file copy, and finally the live URL. The first deploy of a folder creates a new project automatically using the folder name as the slug.

Need to deploy from a different directory without cd'ing in? Pass it as an argument:

kws deploy ~/sites/my-static-site

Next.js and SSR Frameworks (Free Plan)

The KWS Free plan supports Next.js, Nuxt, SvelteKit, Astro, and similar SSR frameworks. Free SSR projects auto-suspend after 5 minutes of inactivity to keep the platform sustainable — the first request after sleep takes about 2-3 seconds to wake the process. Subsequent requests are instant.

If your app needs always-on hosting (no cold starts), upgrade to Pro for 2 always-on slots, Business for 5, or Enterprise for 25. Pin your important SSR projects to a slot from Project Settings → Always-On. Cold starts are a Free/Starter characteristic, not a bug.

What gets cached during sleep?

Static assets (CSS, JS bundles, images in /public) are served directly by Apache and don't need the Node process. Only dynamic pages (SSR routes, API routes) trigger a wake-up.

Want to deploy a static-only Next.js app?

Add output: 'export' to your next.config.js. Your app becomes a fully-static site with zero cold-start penalty.

Command Reference

Command	What it does
`kws login`	Save a Personal Access Token to `~/.kwsrc`.
`kws logout`	Remove the saved token.
`kws whoami`	Show who is signed in (calls `/api/v1/me`).
`kws projects`	List your projects.
`kws projects info <id>`	Show details for one project.
`kws deploy [path]`	Zip a directory and deploy it. Defaults to current directory.
`kws logs <deployment-id>`	Print a deployment's build log.
`kws open [project-id-or-slug]`	Open the project URL in your browser.

Troubleshooting

"Token missing required scope: deployments:read"

You minted a token that has deployments:write but not deployments:read. The CLI needs read access to poll the deploy progress and to fetch build logs. Mint a new token at Settings → API with all three scopes ticked, then run kws login again.

"Cannot GET /403.shtml" or HTTP 404 on upload

This used to happen when the server's web application firewall blocked application/zip uploads. It has been disabled in production. If you still see it, contact support and mention the WAF/ModSecurity rule number from the failed request.

Deploy succeeded but the site is empty

If your project has a custom domain attached but the files are not appearing, the file copy step may have failed silently. Check the build log with kws logs <deployment-id>. Most common cause is a permission error on the destination directory — contact support with the log output.

"command not found: kws" after install

npm global packages install into $(npm config get prefix)/bin which is not always on your PATH. Add it to your shell config:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

How the CLI Talks to KWS

Under the hood, every CLI command calls the KWS REST API at https://katikaws.com/api/v1/*. The CLI is mostly a friendly wrapper around POST /api/v1/deployments (for deploys), GET /api/v1/projects (for listing), and GET /api/v1/me (for whoami).

If you would rather call the API directly — from a CI/CD pipeline, your own script, or another tool — the same Personal Access Token works as a Bearer credential:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://katikaws.com/api/v1/projects

See the REST API documentation for the full endpoint list and request shapes.

Tip: Bookmark /dashboard → Settings → API for token management — revoking and rotating tokens takes one click there.

Was this article helpful?