Documentation

Install, activate, run.

Everything here assumes you have a key. If you do not,that is on the overview page.

Requirements

Node.js 20 LTS or newer
AWS CLI v2, configured with a profile that can reach CloudFormation
Claude Code
Optional: cfn-lint — pip install cfn-lint. Without itclawform validate still runs and reports each missing linter as⊘ skipped, which is distinct from ✓ clean, so a missing tool never reads as a green result.

AWS CloudFormation only today. Other clouds and other infrastructure languages are being built; if you need one of them now, this is not the tool yet.

Step 1

Install the CLI

npm i -g @thejoseki/clawform
clawform --version

One global install. The Claude Code plugin comes out of this package later, after activation — there is nothing else to download.

Step 2

Activate your key

clawform activate <your-key>
clawform license

The key is in your purchase email. clawform license shows what this machine holds; clawform license --check is the silent version for scripts — it exits 1 when unlicensed.

Machines per licence

Activating claims one slot — three on a per-seat licence, ten on a team licence. Moving to a new machine is a deactivation on the old one, not a support ticket:

clawform deactivate

In CI, do not activate

Set CLAWFORM_LICENSE_KEY in the environment instead. It is validated on every run and never takes a slot, so ephemeral runners do not consume the seat you are using.

CLAWFORM_LICENSE_KEY=<your-key> clawform validate cfn/networking.yaml

Offline

A verified licence is re-checked about once a day. If the licence service cannot be reached, Clawform keeps working for 14 daysfrom the last successful check — long enough to survive a trip, short enough that a revoked key does not run forever. CI has no grace window, because a runner that cannot reach the network is a broken runner.

Trial keys

A trial key activates the same way and runs for 14 days from purchase — the end date comes from the licence service, andclawform license shows it. When it lapses, the value commands stop and deploy and rollback keep working; an expired licence never strands a stack. What you fetched stays on your machine — the trial governs support and updates, not your disk.

One machine can use one trial. Activating a trial records a fingerprint of the machine — a hash of hostname, platform, architecture, and machine id — with our service. It identifies the machine, not you; paid keys never touch that register, and nothing else is collected. If a machine is wrongly refused a trial, write tosupport@thejoseki.com and a person will fix it.

Step 3

Install the Claude Code plugin

clawform init plugin              # --global (default)
clawform init plugin --project    # this project only

Unpacks the plugin from your activated copy and registers it with Claude Code. --global installs into ~/.claude;--project into ./.claude so a repository can pin its own copy.

Restart your Claude Code session afterwards so it picks up the new commands.

Step 4

Set up a project

Run this in your own project, not in a Clawform directory. It writes clawform.config.json — the file that holds your customer shortname, region, account ids and frozen stack prefixes. Nothing about any organisation is baked into the tool.

clawform init            # interactive wizard
clawform init --force    # overwrite an existing config

Non-interactive

For CI or a scripted bootstrap, set CLAWFORM_INIT_*environment variables and the wizard skips the prompts:

CLAWFORM_INIT_CUSTOMER=acme CLAWFORM_INIT_REGION=ap-northeast-1 clawform init

AWS credentials

Your profile goes in .claude/settings.local.json under theenv block — per user, gitignored. Clawform never asks for credentials and never sends them anywhere; every AWS call runs locally under the profile you name.

Command reference

Run clawform <command> --help for the full flag list.

Licence

Command	What it does
`activate <key>`	Claim an activation slot on this machine
`license`	Show what this machine holds
`license --check`	Silent; exits 1 when unlicensed
`deactivate`	Release this machine's slot

Setup

Command	What it does
`init`	Write `clawform.config.json` for a project. `--force` overwrites
`init plugin`	Install the Claude Code plugin. `--global` \| `--project`
`ci init`	Generate CI config. `--provider gitlab\|github`, `--source-bucket`, `--cfn-dir`, `--branch`, `--force`

Templates and deploys

Command	What it does
`validate <file>`	cfn-lint, cfn-guard, cfn-nag and `ValidateTemplate`. `--skip-aws` for a box with no credentials
`deploy <file> <env>`	Changeset → confirm → execute. `--params`, `--capabilities`, `--auto-approve`
`diff <stack>`	Local template against the live stack. `--file`
`drift <stack>`	Detect configuration drift on a deployed stack
`rollback <stack>`	Recover a stack stuck in `CREATE_FAILED` or `UPDATE_ROLLBACK_FAILED`

--auto-approve is refused when a change would replace or remove a data resource. That is not configurable.

Day two

Command	What it does
`sync`	Refresh the export catalog and stack inventory from live AWS. `--profile`, `--region`
`status`	Per-stack status, last deploy, last-known drift. `--project`, `--env`
`cost-report`	Month-to-date spend by tag. `--month YYYY-MM`, `--group-by project\|env\|costcenter\|service`

Troubleshooting

What you see	What it means
`needs an activated license`	Run `clawform activate <key>`. In CI, set `CLAWFORM_LICENSE_KEY` instead.
`used all of its activation slots`	All three machines are claimed. Run `clawform deactivate` on one you no longer use.
`rate-limiting this key`	Too many licence calls in a burst. Wait about a minute — repeating immediately extends the limit rather than clearing it.
`rejected this key`	The key is not valid for this product. Check for a transcription error against your purchase email.
`Could not reach the license service`	Network or vendor outage. An already-activated machine keeps working for 14 days from its last successful check.
`⊘ skipped` in validate output	That linter is not installed. Not a failure, and deliberately not shown as `✓ clean` either — a missing tool must never read as a pass.
A command was blocked	The guard refused it before it ran. The message names the safe path to use instead.

Anything else: support@thejoseki.comreaches the person who wrote it.