#Setup

#Install

npm install -g dotsec

npm install --save-dev dotsec
# or
pnpm add -D dotsec
# or
yarn add -D dotsec

{
  "scripts": {
    "dev": "dotsec run -- node server.js",
    "test": "dotsec run -- vitest",
    "build": "dotsec run -- next build"
  }
}

npx dotsec set API_KEY sk-live-xxx

Distribution is npm-only. The obvious crate names on crates.io (dotsec, crypto, dotenv, aws) are owned by unrelated projects, so cargo install isn't available. The npm package ships a native per-platform binary.

Verify the install:

dotsec --version

#Release channels

#Zero-config start

No AWS account, no config file, no setup step required. The first dotsec set auto-creates everything:

dotsec set API_KEY sk-live-xxx --encrypt

This creates:

• .sec — your encrypted secrets file (commit this)
• .sec.key — your age private key (never commit this)

#.sec.key is auto-.gitignored

The first time dotsec set or dotsec init generates a keypair, it makes sure .sec.key is excluded from git. The exact action depends on what it finds in the directory:

The pattern is *.key (not just .sec.key) because once you start using multiple environments — prod.sec.key, staging.sec.key, local.sec.key — a narrower rule would silently leak the ones it doesn't match.

dotsec set API_KEY sk-live-xxx                 # auto-adds *.key
dotsec set API_KEY sk-live-xxx --no-gitignore  # opt out, no .gitignore touched

If anything fails (read-only filesystem, permission issues), dotsec logs a warning and keeps going — committing the key file is ultimately your call.

#Team sharing

Share the .sec.key file with teammates over a secure channel (1Password, Bitwarden, Signal, etc.). Each person puts it alongside their .sec file.

For CI/CD, set the key as an environment variable:

export DOTSEC_PRIVATE_KEY="AGE-SECRET-KEY-1..."

dotsec checks DOTSEC_PRIVATE_KEY before looking for a key file, so this works in any CI system without needing to write files.

Key discovery order:

1. DOTSEC_PRIVATE_KEY environment variable
2. <sec-file>.key file in the same directory

#AWS KMS setup

For teams that need IAM-controlled access and CloudTrail audit logs. With KMS there is no local key file — all the key material lives in AWS's HSM. See On-disk surface area for the threat-model implications.

1. Create a symmetric KMS key and give it an alias:

   key_id=$(aws kms create-key --description "dotsec" \
     --query KeyMetadata.KeyId --output text)
   aws kms create-alias \
     --alias-name alias/dotsec \
     --target-key-id "$key_id"

2. Initialize dotsec with AWS as the provider:

   dotsec init
   # Choose "aws", enter alias/dotsec and your region

3. AWS credentials are picked up automatically from ~/.aws/credentials, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or an instance role.

4. Verify the round-trip:

   dotsec set SMOKE_TEST ok --encrypt
   dotsec show   # SMOKE_TEST decrypts → KMS works

Principals that only need to read secrets (CI, runtime roles) need just kms:Decrypt, and you can scope it to dotsec specifically via the encryption context:

{
  "Effect": "Allow",
  "Action": "kms:Decrypt",
  "Resource": "arn:aws:kms:us-east-1:123456789012:key/...",
  "Condition": {
    "StringEquals": { "kms:EncryptionContext:dotsec:format": "v3" }
  }
}

Writing secrets (dotsec set, rotate-key) additionally needs kms:GenerateDataKey.

#Next steps

• Push to SSM / Secrets Manager for runtime services that read from AWS directly — see @push directives and dotsec push.
• Wire CI without long-lived AWS credentials — see CI/CD → GitHub Actions + KMS + OIDC.
• Read the mechanics — see How KMS envelope encryption works.

#Multiple environments

Each environment gets its own .sec file with its own keypair:

SEC_FILE=.sec.staging dotsec set DB_URL postgres://staging-db
SEC_FILE=.sec.production dotsec set DB_URL postgres://prod-db

Share directives (types, constraints) across environments using a schema file:

dotsec extract-schema   # creates dotsec.schema from .sec
dotsec validate         # validates .sec against schema

See the directives guide for details.