Skip to main content

​
Get started in four steps

This guide gets you from zero to a working Tank setup with your first skill installed.
1

Install the Tank CLI

Choose your package manager:
npm install -g @tankpkg/cli
Verify the installation:
tank --version
For other installation methods (shell script, binary), see the Installation Guide.
2

Authenticate with GitHub

Tank uses GitHub OAuth for authentication. Run:
tank login
What happens:
  1. Opens your browser to GitHub OAuth
  2. You authorize Tank
  3. CLI polls for completion
  4. API key stored in ~/.tank/config.json
Example output:
Starting login...
Opened browser for authentication.
Waiting for authorization...
✓ Logged in as your-username
Verify your session:
tank whoami
Your API key (prefix tank_) is stored locally. Tank never stores your GitHub credentials.
3

Create a skills.json manifest

Navigate to your project directory and initialize:
cd my-agent-project
tank init
Interactive prompts:
? Skill name: my-agent-project
? Version: 0.1.0
? Description: My AI agent project
? Make this skill private? No
? Author: Your Name
✓ Created skills.json
Generated skills.json:
skills.json
{
  "name": "my-agent-project",
  "version": "0.1.0",
  "description": "My AI agent project",
  "visibility": "public",
  "skills": {},
  "permissions": {
    "network": { "outbound": [] },
    "filesystem": { "read": [], "write": [] },
    "subprocess": false
  }
}
The permissions block is your security boundary. Skills exceeding these permissions will fail to install.
4

Install your first skill

Install a skill from the Tank registry:
tank install @vercel/next-skill
What happens:
  1. Resolves latest version matching semver range
  2. Fetches skill metadata and download URL
  3. Downloads tarball to temp directory
  4. Verifies SHA-512 integrity hash
  5. Extracts with security filters (no symlinks, path traversal, etc.)
  6. Writes to ~/.tank/skills/@vercel/[email protected]/
  7. Updates skills.json and generates skills.lock
Example output:
✓ Resolved @vercel/[email protected]
✓ Downloading tarball...
✓ Verified integrity (sha512)
✓ Extracting skill...
✓ Updated skills.json
✓ Updated skills.lock
✓ Installed @vercel/[email protected]
Generated skills.lock:
skills.lock
{
  "lockfileVersion": 1,
  "skills": {
    "@vercel/[email protected]": {
      "resolved": "https://registry.tankpkg.dev/@vercel/next-skill/2.1.3",
      "integrity": "sha512-abc123...",
      "auditScore": 9,
      "permissions": {
        "filesystem": { "read": ["./src/**"] },
        "network": false,
        "subprocess": false
      }
    }
  }
}
Permission budget check: If the skill’s permissions exceed your skills.json budget, installation fails. Update your permissions first.

​
Next Steps

Now that you have Tank working, explore these workflows:

View Installed Skills

tank permissions
Shows resolved permissions for all installed skills.

Security Audit

tank audit
Displays security analysis and audit scores for all skills.

Update Skills

tank update @vercel/next-skill
Updates within semver range from skills.json.

Search Registry

tank search "nextjs"
Full-text search across skill names and descriptions.

​
Common Workflows

​
Installing from lockfile (CI/CD)

When your team clones the repo or in CI, install exact versions from lockfile: 
tank install
This is like npm ci — installs exactly what’s in skills.lock, no version resolution.

​
Updating all skills

Update all skills within their semver ranges: 
tank update

​
Removing a skill

Remove from lockfile and delete files: 
tank remove @vercel/next-skill

​
Verify lockfile integrity

Check that installed skills match lockfile hashes: 
tank verify

​
Understanding Output

​
Audit Score

Tank displays audit scores (0-10) during install:
  • 9-10: Excellent — low risk
  • 7-8: Good — minor issues
  • 5-6: Needs review — moderate risk
  • 0-4: High risk — review carefully
You can set a minimum threshold in skills.json: 
{
  "audit": {
    "min_score": 7
  }
}

​
Permission Budget Failures

If a skill exceeds your permission budget: 
✗ Permission budget exceeded for @org/skill:
  Required: filesystem.write = ["./data/**"]
  Allowed: filesystem.write = []
  
Update your skills.json permissions to allow this skill.
Review the skill’s permissions with tank info @org/skill before expanding your budget.

​
Troubleshooting

The CLI wasn’t added to your PATH. Try:
  • Restart your terminal
  • Check install location: npm list -g @tankpkg/cli
  • Use npx @tankpkg/cli instead
GitHub OAuth took too long. Common fixes:
  • Check your network connection
  • Disable VPN temporarily
  • Try again: tank logout && tank login
The downloaded tarball doesn’t match the expected hash. This could indicate:
  • Network corruption (retry)
  • Registry issue (check status)
  • Supply chain attack (report immediately)
Check file permissions:
ls -la ~/.tank/
The CLI needs write access to ~/.tank/ for config and skills.
Need more help? Run tank doctor to diagnose configuration, authentication, and network issues.

​
What’s Next?

Installation Guide

Detailed installation for all platforms, package managers, and binary releases.

Core Concepts

Deep dive into skills, manifests, lockfiles, and permissions.

CLI Commands

Complete reference for all 16 Tank CLI commands.

Security Pipeline

Learn how Tank’s 6-stage security scanning works.

Build docs developers (and LLMs) love

Get started for freeTalk to us