CLI Reference¶

PikoCI provides three top-level commands: server, worker, and client, plus utility commands user-password and worker-token.

Global structure¶

pikoci server       [flags]          # Start the server
pikoci worker       [flags]          # Start a standalone worker
pikoci client       [flags] <cmd>    # Interact with the API
pikoci user-password [flags]         # Generate hashed passwords
pikoci worker-token  [flags]         # Generate a worker authentication token

client¶

Manage pipelines and jobs via the PikoCI API.

Global flags¶

Flag	Alias	Default	Required	Description
`--url`	`-u`	`localhost:4000`	yes	PikoCI server URL
`--jwt`			no	JWT token (if not provided, reads from `$XDG_CONFIG_HOME/pikoci/authentication`)

Authenticate and store the JWT locally.

pikoci client -u localhost:8080 login -u admin -p admin123

Flag	Alias	Required	Description
`--username`	`-u`	yes	Username
`--password`	`-p`	yes	Password

pipelines¶

Pipeline management commands. All require --team-canonical (default: main).

Flag	Alias	Default	Description
`--team-canonical`	`-tc`	`main`	Team scope

pipelines create¶

pikoci client -u localhost:8080 pipelines create \
  -n my-pipeline -c pipeline.hcl -v vars.json

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name
`--config`	`-c`	yes	Path to HCL config file
`--vars`	`-v`	no	Path to JSON vars file

pipelines update¶

pikoci client -u localhost:8080 pipelines update \
  -n my-pipeline -c pipeline.hcl --public

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name
`--config`	`-c`	yes	Path to HCL config file
`--vars`	`-v`	no	Path to JSON vars file
`--public`		no	Make the pipeline publicly visible

pipelines list¶

pikoci client -u localhost:8080 pipelines list

pipelines get¶

pikoci client -u localhost:8080 pipelines get -n my-pipeline

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name

pipelines graph¶

Export the pipeline as a DOT graph.

pikoci client -u localhost:8080 pipelines graph -n my-pipeline | dot -Tsvg > pipeline.svg

Flag	Alias	Default	Required	Description
`--name`	`-n`, `-pn`		yes	Pipeline name
`--format`	`-f`	`dot`	no	Output format

pipelines delete¶

pikoci client -u localhost:8080 pipelines delete -n my-pipeline

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name

jobs¶

Job management commands. Require --team-canonical and --pipeline-name.

Flag	Alias	Required	Description
`--team-canonical`	`-tc`	yes	Team scope
`--pipeline-name`	`-pn`	yes	Pipeline name

jobs get¶

pikoci client -u localhost:8080 jobs get -tc main -pn my-pipeline -n my-job

Flag	Alias	Required	Description
`--job-name`	`-n`, `-jn`	yes	Job name

jobs trigger¶

Manually trigger a job.

pikoci client -u localhost:8080 jobs trigger -tc main -pn my-pipeline -n my-job

Flag	Alias	Required	Description
`--job-name`	`-n`, `-jn`	yes	Job name

users¶

User management commands.

users create¶

pikoci client users create --username newuser --password secret123

Flag	Required	Description
`--username`	yes	Username for the new User
`--password`	yes	Password for the new User

users list¶

pikoci client users list

teams¶

Team management commands.

teams create¶

pikoci client teams create --name my-team

Flag	Required	Description
`--name`	yes	Name of the Team

teams list¶

pikoci client teams list

teams get¶

pikoci client teams get --canonical my-team

Flag	Required	Description
`--canonical`	yes	Canonical of the Team

teams update¶

pikoci client teams update --canonical my-team --name new-name

Flag	Required	Description
`--canonical`	yes	Canonical of the Team
`--name`	yes	New name for the Team

teams delete¶

pikoci client teams delete --canonical my-team

Flag	Required	Description
`--canonical`	yes	Canonical of the Team

teams members¶

Team member management. All subcommands require --team-canonical.

Flag	Required	Description
`--team-canonical`	yes	Team scope

teams members create¶

pikoci client teams members create --team-canonical my-team --username user1 --admin

Flag	Required	Description
`--username`	yes	Username of the member to add
`--admin`	no	Whether the member is a team admin

teams members update¶

pikoci client teams members update --team-canonical my-team --username user1 --admin

Flag	Required	Description
`--username`	yes	Username of the member to update
`--admin`	no	Whether the member is a team admin

teams members delete¶

pikoci client teams members delete --team-canonical my-team --username user1

Flag	Required	Description
`--username`	yes	Username of the member to remove

builds¶

Build management commands. All require --team-canonical, --pipeline-name, and --job-name.

Flag	Required	Description
`--team-canonical`	yes	Team scope
`--pipeline-name`	yes	Pipeline name
`--job-name`	yes	Job name

builds list¶

pikoci client builds list --team-canonical main --pipeline-name my-pipeline --job-name my-job

builds get¶

pikoci client builds get --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds delete¶

pikoci client builds delete --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds cancel¶

pikoci client builds cancel --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds retry¶

pikoci client builds retry --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

resources¶

Resource management commands. All require --team-canonical and --pipeline-name.

Flag	Required	Description
`--team-canonical`	yes	Team scope
`--pipeline-name`	yes	Pipeline name

resources get¶

pikoci client resources get --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources trigger¶

pikoci client resources trigger --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources versions¶

pikoci client resources versions --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources webhook-regenerate¶

pikoci client resources webhook-regenerate --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

triggers¶

Trigger management commands. All require --team-canonical.

Flag	Required	Description
`--team-canonical`	yes	Team scope

triggers create¶

pikoci client triggers create --team-canonical main --name my-trigger --version '{"ref": "abc123"}'

Flag	Required	Description
`--name`	yes	Name of the Trigger
`--version`	yes	Version data as a JSON string

triggers list¶

pikoci client triggers list --team-canonical main --name my-trigger --after 0

Flag	Required	Description
`--name`	yes	Name of the Trigger
`--after`	no	List triggers after this ID (default: 0)

user-password¶

Generate a USERNAME:HASHED_PASSWORD string for the server's --users flag.

pikoci user-password -u myuser -p mypassword
# Output: myuser:$2a$10$...

Flag	Alias	Required	Description
`--username`	`-u`	yes	Username
`--password`	`-p`	yes	Plain-text password

worker-token¶

Generate a pre-signed worker authentication token. This avoids distributing the raw JWT secret to worker machines.

pikoci worker-token --jwt-secret my-secret
# Output: eyJhbG...

Flag	Default	Required	Description
`--jwt-secret`		yes	JWT secret used by the server

The server also logs a worker token on startup when --run-worker=false.

server¶

See Server Configuration.

worker¶

See Running Workers Separately.